@oh-my-pi/pi-coding-agent 17.0.5 → 17.0.7

package/src/modes/rpc/rpc-frame.ts

@@ -0,0 +1,156 @@
+import { isDeepStrictEqual } from "node:util";
+import { isRecord } from "@oh-my-pi/pi-utils";
+
+/** Maximum UTF-8 size of one newline-delimited RPC frame, including the newline. */
+export const MAX_RPC_FRAME_BYTES = 1024 * 1024;
+
+interface ShrinkPass {
+	stringCap: number;
+	arrayLimit: number;
+	objectLimit: number;
+}
+
+const SHRINK_PASSES: readonly ShrinkPass[] = [
+	{ stringCap: 256 * 1024, arrayLimit: 512, objectLimit: 512 },
+	{ stringCap: 64 * 1024, arrayLimit: 256, objectLimit: 256 },
+	{ stringCap: 16 * 1024, arrayLimit: 128, objectLimit: 128 },
+	{ stringCap: 4 * 1024, arrayLimit: 64, objectLimit: 64 },
+	{ stringCap: 1024, arrayLimit: 32, objectLimit: 32 },
+	{ stringCap: 256, arrayLimit: 8, objectLimit: 16 },
+	{ stringCap: 64, arrayLimit: 1, objectLimit: 8 },
+];
+
+const STRING_ELISION_RESERVE = 80;
+const METADATA_STRING_CAP = 1024;
+
+function serializedFrameBytes(json: string): number {
+	return Buffer.byteLength(json, "utf8") + 1;
+}
+
+function shrinkString(value: string, cap: number): string {
+	if (value.length <= cap) return value;
+	const headLength = Math.max(0, cap - STRING_ELISION_RESERVE);
+	return `${value.slice(0, headLength)}\n…[${value.length - headLength} chars elided for RPC frame]`;
+}
+
+function shrinkValue(value: unknown, pass: ShrinkPass): unknown {
+	if (typeof value === "string") return shrinkString(value, pass.stringCap);
+	if (Array.isArray(value)) {
+		const keep = Math.min(value.length, pass.arrayLimit);
+		const output: unknown[] = new Array(keep + (keep < value.length ? 1 : 0));
+		for (let index = 0; index < keep; index++) output[index] = shrinkValue(value[index], pass);
+		if (keep < value.length) output[keep] = `…[${value.length - keep} items elided for RPC frame]`;
+		return output;
+	}
+	if (isRecord(value)) {
+		const entries = Object.entries(value);
+		const keep = Math.min(entries.length, pass.objectLimit);
+		const output: Record<string, unknown> = {};
+		for (let index = 0; index < keep; index++) {
+			const [key, item] = entries[index];
+			output[key] = shrinkValue(item, pass);
+		}
+		if (keep < entries.length) output.rpcFrameElidedKeys = entries.length - keep;
+		return output;
+	}
+	return value;
+}
+
+function jsonSnapshot(value: unknown): unknown {
+	const json = JSON.stringify(value);
+	return json === undefined ? undefined : JSON.parse(json);
+}
+
+function encodedMessageSnapshot(encoded: string): { message: unknown } | undefined {
+	const frame = JSON.parse(encoded);
+	return isRecord(frame) && frame.type === "message_end" && Object.hasOwn(frame, "message")
+		? { message: frame.message }
+		: undefined;
+}
+
+function compactTerminalFrame(
+	frame: object,
+	streamedMessageCount: number,
+	streamedMessages?: readonly unknown[],
+): object {
+	if (!isRecord(frame) || frame.type !== "agent_end" || !Array.isArray(frame.messages)) return frame;
+	let streamed = Number.isSafeInteger(streamedMessageCount)
+		? Math.min(Math.max(0, streamedMessageCount), frame.messages.length)
+		: 0;
+	if (streamedMessages) {
+		streamed = 0;
+		const limit = Math.min(streamedMessages.length, frame.messages.length);
+		while (
+			streamed < limit &&
+			isDeepStrictEqual(streamedMessages[streamed], jsonSnapshot(frame.messages[streamed]))
+		) {
+			streamed++;
+		}
+	}
+	return {
+		...frame,
+		messages: frame.messages.slice(streamed),
+		messageCount: frame.messages.length,
+	};
+}
+
+function overflowFrame(frame: object): object {
+	if (!isRecord(frame)) return { type: "rpc_frame_error", error: "RPC frame exceeded the transport limit" };
+	if (frame.type === "response") {
+		return {
+			id: typeof frame.id === "string" ? shrinkString(frame.id, METADATA_STRING_CAP) : undefined,
+			type: "response",
+			command: typeof frame.command === "string" ? shrinkString(frame.command, METADATA_STRING_CAP) : "unknown",
+			success: false,
+			error: "RPC response exceeded the transport limit",
+		};
+	}
+	if (frame.type === "agent_end") {
+		return {
+			type: "agent_end",
+			messages: [],
+			messageCount: typeof frame.messageCount === "number" ? frame.messageCount : 0,
+		};
+	}
+	return {
+		type: "rpc_frame_error",
+		originalType: typeof frame.type === "string" ? shrinkString(frame.type, METADATA_STRING_CAP) : undefined,
+		error: "RPC frame exceeded the transport limit",
+	};
+}
+
+/** Serialize a complete JSONL frame while enforcing the transport byte ceiling. */
+export function encodeRpcFrame(frame: object, streamedMessageCount = 0, streamedMessages?: readonly unknown[]): string {
+	let json = JSON.stringify(frame);
+	if (serializedFrameBytes(json) <= MAX_RPC_FRAME_BYTES) return `${json}\n`;
+	if (isRecord(frame) && frame.type === "response") {
+		return `${JSON.stringify(overflowFrame(frame))}\n`;
+	}
+
+	const compacted = compactTerminalFrame(frame, streamedMessageCount, streamedMessages);
+	json = JSON.stringify(compacted);
+	if (serializedFrameBytes(json) <= MAX_RPC_FRAME_BYTES) return `${json}\n`;
+
+	for (const pass of SHRINK_PASSES) {
+		json = JSON.stringify(shrinkValue(compacted, pass));
+		if (serializedFrameBytes(json) <= MAX_RPC_FRAME_BYTES) return `${json}\n`;
+	}
+
+	return `${JSON.stringify(overflowFrame(compacted))}\n`;
+}
+
+/** Stateful encoder that tracks which messages a client has already received. */
+export class RpcFrameEncoder {
+	#streamedMessages: unknown[] = [];
+
+	encode(frame: object): string {
+		if (isRecord(frame) && frame.type === "agent_start") this.#streamedMessages = [];
+		const encoded = encodeRpcFrame(frame, this.#streamedMessages.length, this.#streamedMessages);
+		if (!isRecord(frame)) return encoded;
+		if (frame.type === "message_end") {
+			const snapshot = encodedMessageSnapshot(encoded);
+			if (snapshot) this.#streamedMessages.push(snapshot.message);
+		} else if (frame.type === "agent_end" && frame.willContinue !== true) this.#streamedMessages = [];
+		return encoded;
+	}
+}

package/src/modes/rpc/rpc-mode.ts

@@ -34,6 +34,7 @@ import type { EventBus } from "../../utils/event-bus";
 import { initializeExtensions } from "../runtime-init";
 import { isRpcHostToolResult, isRpcHostToolUpdate, RpcHostToolBridge } from "./host-tools";
 import { isRpcHostUriResult, RpcHostUriBridge } from "./host-uris";
+import { RpcFrameEncoder } from "./rpc-frame";
 import { claimRpcInput } from "./rpc-input";
 import { RpcSubagentRegistry, readRpcSubagentTranscript } from "./rpc-subagents";
 import type {
@@ -617,9 +618,10 @@ export async function runRpcMode(
 	// may write there.
 	process.env.PI_NOTIFICATIONS = "off";
 
-	process.stdout.write(`${JSON.stringify({ type: "ready" })}\n`);
+	const frameEncoder = new RpcFrameEncoder();
+	process.stdout.write(frameEncoder.encode({ type: "ready" }));
 	const output = (obj: RpcResponse | RpcExtensionUIRequest | object) => {
-		process.stdout.write(`${JSON.stringify(obj)}\n`);
+		process.stdout.write(frameEncoder.encode(obj));
 	};
 	const emitRpcTitles = shouldEmitRpcTitles();
 

package/src/modes/setup-wizard/index.ts

@@ -2,6 +2,7 @@ import type { Settings } from "../../config/settings";
 import { CURRENT_SETUP_VERSION } from "../setup-version";
 import type { InteractiveModeContext } from "../types";
 import { glyphSetupScene } from "./scenes/glyph";
+import { modelSetupScene } from "./scenes/model";
 import { providersSetupScene } from "./scenes/providers";
 import { themeSetupScene } from "./scenes/theme";
 import type { SetupScene } from "./scenes/types";
@@ -14,6 +15,7 @@ export { CURRENT_SETUP_VERSION };
 
 export const ALL_SCENES = [
 	providersSetupScene,
+	modelSetupScene,
 	glyphSetupScene,
 	themeSetupScene,
 ] as const satisfies readonly SetupScene[];

package/src/modes/setup-wizard/scenes/model.ts

@@ -0,0 +1,134 @@
+import type { Model } from "@oh-my-pi/pi-ai";
+import type { SgrMouseEvent } from "@oh-my-pi/pi-tui";
+import {
+	buildBrowserItems,
+	ModelBrowser,
+	resolveRoleAssignments,
+	sortModelItems,
+} from "../../components/model-browser";
+import { theme } from "../../theme/theme";
+import type { SetupScene, SetupSceneController, SetupSceneHost } from "./types";
+
+const MAX_VISIBLE_MODELS = 10;
+const WIZARD_SCREEN_RESERVE = 22;
+
+class ModelSceneController implements SetupSceneController {
+	title = "Choose your default model";
+	subtitle = "Search configured models and save the model used for new sessions.";
+	#browser: ModelBrowser;
+	#status: string | undefined;
+	#selecting = false;
+	#disposed = false;
+	#browserRowStart = 2;
+
+	constructor(private readonly host: SetupSceneHost) {
+		this.#browser = new ModelBrowser(host.ctx.settings);
+		this.#browser.onActivate = item => {
+			void this.#select(item.model, item.selector);
+		};
+		this.#browser.onCancel = () => host.finish("skipped");
+		this.#syncModels();
+	}
+
+	async onMount(): Promise<void> {
+		this.#status = theme.fg("muted", "Discovering available models…");
+		this.host.requestRender();
+		await this.#refreshModels();
+	}
+
+	dispose(): void {
+		this.#disposed = true;
+	}
+
+	invalidate(): void {
+		this.#browser.invalidate();
+	}
+
+	handleInput(data: string): void {
+		if (this.#selecting) return;
+		this.#browser.handleInput(data);
+	}
+
+	routeMouse(event: SgrMouseEvent, line: number): void {
+		if (this.#selecting) return;
+		this.#browser.routeMouse(event, line - this.#browserRowStart);
+	}
+
+	render(width: number): readonly string[] {
+		const visibleRows = Math.max(
+			1,
+			Math.min(MAX_VISIBLE_MODELS, this.host.ctx.ui.terminal.rows - WIZARD_SCREEN_RESERVE),
+		);
+		this.#browser.setMaxVisible(visibleRows);
+		const lines = [
+			this.#status ?? theme.fg("muted", "Type to search. Enter saves the highlighted model as your default."),
+			"",
+		];
+		this.#browserRowStart = lines.length;
+		lines.push(...this.#browser.render(width));
+		return lines;
+	}
+
+	#syncModels(): void {
+		const registry = this.host.ctx.session.modelRegistry;
+		const available = registry.getAvailable();
+		const roles = resolveRoleAssignments(this.host.ctx.settings, registry.getAll(), available);
+		const storage = this.host.ctx.settings.getStorage();
+		const items = buildBrowserItems(available);
+		sortModelItems(items, { roles, mruOrder: storage?.getModelUsageOrder() ?? [] });
+		this.#browser.setRoles(roles);
+		this.#browser.setMruOrder(storage?.getModelUsageOrder() ?? []);
+		this.#browser.setPerfStats(storage?.getModelPerf() ?? new Map());
+		this.#browser.setItems(items);
+
+		const current = this.host.ctx.session.model;
+		if (current) {
+			const selector = `${current.provider}/${current.id}`;
+			this.#browser.setCurrentSelector(selector);
+			this.#browser.selectSelector(selector);
+		}
+	}
+
+	async #refreshModels(): Promise<void> {
+		try {
+			await this.host.ctx.session.modelRegistry.refresh("online-if-uncached");
+			if (this.#disposed) return;
+			this.#syncModels();
+			this.#status = undefined;
+			this.host.requestRender();
+		} catch (error) {
+			if (this.#disposed) return;
+			this.#status = theme.fg("error", error instanceof Error ? error.message : String(error));
+			this.host.requestRender();
+		}
+	}
+
+	async #select(model: Model, selector: string): Promise<void> {
+		if (this.#selecting) return;
+		this.#selecting = true;
+		this.#status = theme.fg("muted", `Saving ${selector} as the default model…`);
+		this.host.requestRender();
+		try {
+			const projectScope = this.host.ctx.settings.get("modelRoleStorage") === "project";
+			await this.host.ctx.session.setModel(model, "default", { selector, persist: !projectScope });
+			if (projectScope) {
+				this.host.ctx.settings.setProjectModelRole("default", selector);
+			}
+			await this.host.ctx.settings.flush();
+			if (!this.#disposed) this.host.finish("done");
+		} catch (error) {
+			if (this.#disposed) return;
+			this.#selecting = false;
+			this.#status = theme.fg("error", error instanceof Error ? error.message : String(error));
+			this.host.requestRender();
+		}
+	}
+}
+
+/** Setup step that assigns one available model to the persisted default role. */
+export const modelSetupScene: SetupScene = {
+	id: "model",
+	title: "Choose your default model",
+	minVersion: 1,
+	mount: host => new ModelSceneController(host),
+};

package/src/modes/utils/ui-helpers.ts

@@ -301,14 +301,18 @@ export class UiHelpers {
 		let pendingUsage: Usage | undefined;
 		let pendingUsageDuration: number | undefined;
 		let pendingUsageTtft: number | undefined;
+		let pendingUsageTimestamp: number | undefined;
 		const flushPendingUsage = () => {
 			if (!pendingUsage) return;
 			readGroup?.seal();
 			readGroup = null;
-			this.ctx.chatContainer.addChild(createUsageRowBlock(pendingUsage, pendingUsageDuration, pendingUsageTtft));
+			this.ctx.chatContainer.addChild(
+				createUsageRowBlock(pendingUsage, pendingUsageDuration, pendingUsageTtft, pendingUsageTimestamp),
+			);
 			pendingUsage = undefined;
 			pendingUsageDuration = undefined;
 			pendingUsageTtft = undefined;
+			pendingUsageTimestamp = undefined;
 		};
 		// Rebuild-time mirror of the event controller's displaceable-poll
 		// bookkeeping: a `hub` wait that found every watched job still running is
@@ -509,6 +513,7 @@ export class UiHelpers {
 						: undefined;
 				pendingUsageDuration = message.duration;
 				pendingUsageTtft = message.ttft;
+				pendingUsageTimestamp = message.timestamp;
 			} else if (message.role === "toolResult") {
 				const pendingReadComponent = this.ctx.pendingTools.get(message.toolCallId);
 				const isReadGroupResult =

package/src/prompts/system/workflow-notice.md

@@ -1,89 +1,104 @@
 <system-notice>
-The user's message above contains the **workflowz** keyword: drive this task as a deterministic multi-subagent workflow. Use the `task` tool {{#if taskBatch}}for batched fan-out{{else}}once per independent subagent{{/if}} — to be comprehensive (decompose and cover in parallel), to be confident (independent perspectives and adversarial checks before you commit), or to take on scale one context can't hold (audits, migrations, broad sweeps). This overrides any default tendency to do the whole task inline when fanning out would be more thorough.
+The user's message above contains the **workflowz** keyword: drive this task as a deterministic multi-subagent workflow. Author the orchestration in the `eval` tool and fan out subagents — to be comprehensive (decompose and cover in parallel), to be confident (independent perspectives and adversarial checks before you commit), or to take on scale one context can't hold (audits, migrations, broad sweeps). This overrides any default tendency to do the whole task inline when fanning out would be more thorough.
 
 <when>
-Worth it when the task benefits from decomposition + parallel coverage, or from independent/adversarial cross-checking before you commit. For a quick lookup or single edit, just do it directly — don't spin up agents. Scout inline first (list the files, scope the diff, find the call sites) to discover the work list, then fan out over it. Common shapes:
-- **Understand** — parallel readers over subsystems → structured map.
-- **Design** — independent approaches → scored synthesis.
-- **Review** — split dimensions → find per dimension → adversarially verify each finding.
-- **Research** — multi-modal sweep → deep-read the hits → synthesize.
-- **Migrate** — discover sites → transform each → verify.
+Worth it when the task benefits from decomposition + parallel coverage, or from independent/adversarial cross-checking before you commit. For a quick lookup or single edit, just do it directly — don't spin up agents. Scout inline FIRST (list the files, scope the diff, find the call sites) to discover the work-list, then fan out over it — you don't need to know the shape before the *task*, only before the *fan-out*. Common shapes, each a well-scoped `eval` call you can chain across turns:
+- **Understand** — parallel readers over subsystems → structured map
+- **Design** — judge panel of N independent approaches → scored synthesis
+- **Review** — split into dimensions → find per dimension → adversarially verify each finding
+- **Research** — multi-modal sweep → deep-read the hits → synthesize
+- **Migrate** — discover sites → transform each → verify
 </when>
 
-<task-contract>
-{{#if taskBatch}}
-Call `task` once per independent fan-out batch. Put shared background in `context`, and put each independent work item in `tasks[]`. Do not emulate batching with shell loops or eval helper APIs.
-
-`context` must carry the shared contract:
-
-    # Goal
-    What the batch accomplishes.
-    # Constraints
-    Rules, non-goals, permissions, and verification limits.
-    # Contract
-    Shared interfaces, output shape, branch/base assumptions, and coordination rules.
-
-Each task assignment must be self-contained:
-
-    # Target
-    Exact files, symbols, subsystem, or evidence surface; explicit non-goals.
-    # Change
-    What to inspect or modify, step by step, including APIs and patterns to reuse.
-    # Acceptance
-    Observable result, return packet, and local verification. Subagents skip formatters,
-    linters, and project-wide tests; the parent runs shared proof once.
-{{else}}
-Call `task` once per independent subagent. Put the full shared background and the leaf work in that call's `assignment`. Do not pass `context` or `tasks[]`: the flat task schema rejects them when batch calls are disabled.
-
-Each assignment must be self-contained:
-
-    # Target
-    Exact files, symbols, subsystem, or evidence surface; explicit non-goals.
-    # Change
-    Shared background plus what to inspect or modify, step by step, including APIs and patterns to reuse.
-    # Acceptance
-    Observable result, return packet, and local verification. Subagents skip formatters,
-    linters, and project-wide tests; the parent runs shared proof once.
-{{/if}}
+<helpers>
+State persists across eval calls, so scout in one call and fan out in the next. Every eval call has:
+
+- `agent(prompt, *, agent="task", model=None, label=None, schema=None, isolated=None, apply=None, merge=None, handle=False)` — run ONE subagent; returns its final text, or the validated object when `schema` (a JSON Schema dict) is given. With `schema` the subagent is forced to emit structured output that is validated for you — branch on the object, not on parsed prose. `agent` picks a discovered agent ("explore", "reviewer", …); `label` names the artifact. Shared background goes in a `local://` file referenced from each prompt, not a parameter. Subagents are told their final text IS the return value, so they hand back raw data. `agent()` blocks until the subagent finishes. Recursion follows `task.maxRecursionDepth` (default 2; a negative value disables the cap): main agent depth = 0, each `agent()` child increments depth by 1, and, when the cap is non-negative, a spawner may call `agent()` only while its current `taskDepth < cap`. Pass `isolated=True` to run the spawn in a copy-on-write worktree so parallel `agent()` calls can edit overlapping files safely — strict opt-in, mirrors the `task` tool, defaults off regardless of `task.isolation.mode`; `isolated=True` while the setting is `"none"` errors out instead of silently downgrading. With isolation, `apply=False` keeps changes in the worktree, and `merge=False` forces patch mode even when the setting is `"branch"`. Captured root patch path, branch name, nested repo patches, and apply summary reach the workflow through `handle=True` — combine it with `apply=False` (or `apply=False, schema=…`) and read `node["patch_path"]`, `node["branch_name"]`, `node["nested_patches"]`, `node["changes_applied"]`, `node["isolation_summary"]` (JS: same keys camelCased) to recover artifacts.
+- `parallel(thunks)` — run zero-arg callables concurrently through a bounded pool, preserving input order; returns once all finish. The pool is bounded by the session's `task` concurrency — don't hand-tune it; fan out as wide as the work divides. A thunk that raises propagates — wrap risky work in `try/except` inside the thunk to keep partial results. In a loop, bind each closure's value with a default arg (`lambda d=d: …`) or every thunk captures the last one.
+- `pipeline(items, *stages)` — map items through `stages` left-to-right. There is a BARRIER between stages: ALL items clear stage N before stage N+1 begins. Each stage is a one-arg callable; stage 1 gets the original item, later stages get the previous result. Same pool width as `parallel()`.
+- `completion(prompt, *, model="default", system=None, schema=None)` — oneshot, stateless model call (no tools, no history). Tiers: "smol", "default", "slow". Cheap classification/scoring inside a fan-out.
+- `log(message)` — emit a progress line above the status tree. `phase(title)` — start a phase; the status lines that follow group under it.
+- `budget` — `budget.total` (output-token ceiling, or `None` when none is set), `budget.spent()` (tokens spent this turn — main loop + eval subagents), `budget.remaining()` (`math.inf` when total is `None`), `budget.hard` (whether it's enforced). A ceiling is set by the user: `+Nk` in their message is advisory (you self-limit via `budget.remaining()`), `+Nk!` (or Goal Mode) is hard — `agent()` refuses to spawn once spent reaches it. Gate loops on `budget.total` first, since it's `None` when the user set no budget.
+
+Everything runs INLINE and synchronously inside the eval call — no background mode, no resume, no separate progress app. Each eval call is one well-scoped fan-out; chain several across calls and turns for multi-phase work, reading each result before you decide the next phase.
+</helpers>
 
 <structure>
-Decompose first, then {{#if taskBatch}}batch the independent leaves{{else}}issue one independent task call per leaf in the same turn{{/if}}:
-
-{{#if taskBatch}}
-    task(
-      context: "# Goal\nReview the auth diff…\n# Constraints\nRead-only…\n# Contract\nReturn findings as severity/file/line/fix…",
-      tasks: [
-        { id: "AuthOwner", role: "Auth Storage Reviewer", assignment: "# Target\npackages/ai/src/auth-storage.ts\n# Change\nTrace credential selection…\n# Acceptance\nReturn confirmed findings only…" },
-        { id: "PromptOwner", role: "Prompt Contract Reviewer", assignment: "# Target\npackages/coding-agent/src/prompts/**\n# Change\nCheck active-tool guidance…\n# Acceptance\nReturn mismatches and exact prompt lines…" },
-      ]
-    )
-{{else}}
-    task(
-      role: "Auth Storage Reviewer",
-      assignment: "# Target\npackages/ai/src/auth-storage.ts\n# Change\nReview the auth diff. Shared contract: read-only; return findings as severity/file/line/fix.\n# Acceptance\nReturn confirmed findings only…"
-    )
-    task(
-      role: "Prompt Contract Reviewer",
-      assignment: "# Target\npackages/coding-agent/src/prompts/**\n# Change\nCheck active-tool guidance. Shared contract: read-only; return mismatches and exact prompt lines.\n# Acceptance\nReturn confirmed findings only…"
-    )
-{{/if}}
-
-{{#if taskBatch}}Prefer one wide batch over serial subagent calls when work items do not share files. If tasks overlap, name the overlap and have agents coordinate through IRC before editing.{{else}}Prefer issuing all independent task calls in one assistant turn over serial dispatch when work items do not share files. If tasks overlap, name the overlap and have agents coordinate through IRC before editing.{{/if}}
+For independent per-item chains (review → verify, fetch → extract → score), wrap the WHOLE chain in one function and run it with `parallel()` — then each item flows through its own steps without waiting on the others:
+
+**Python (`eval`, Python backend):**
+
+    DIMENSIONS = [{"key": "bugs", "prompt": "…"}, {"key": "perf", "prompt": "…"}]
+    def review_and_verify(d):
+        found = agent(d["prompt"], label=f"review:{d['key']}", schema=FINDINGS_SCHEMA)
+        return parallel([lambda f=f: {**f, "verdict": agent(
+            f"Refute if you can (default refuted when unsure): {f['title']}",
+            label=f"verify:{f['file']}", schema=VERDICT_SCHEMA)} for f in found["findings"]])
+    phase("Review")
+    results = parallel([lambda d=d: review_and_verify(d) for d in DIMENSIONS])
+    confirmed = [f for group in results for f in group if f["verdict"]["is_real"]]
+
+**JavaScript (`eval`, JavaScript backend):**
+
+    const DIMENSIONS = [{ key: "bugs", prompt: "…" }, { key: "perf", prompt: "…" }];
+    async function reviewAndVerify(d) {
+        const found = await agent(d.prompt, {
+            label: `review:${d.key}`,
+            schema: FINDINGS_SCHEMA,
+        });
+        return await parallel(found.findings.map((f) => async () => ({
+            …f,
+            verdict: await agent(
+                `Refute if you can (default refuted when unsure): ${f.title}`,
+                { label: `verify:${f.file}`, schema: VERDICT_SCHEMA },
+            ),
+        })));
+    }
+    phase("Review");
+    const results = await parallel(DIMENSIONS.map((d) => async () => reviewAndVerify(d)));
+    const confirmed = results.flat().filter((f) => f.verdict.is_real);
+Reach for `pipeline()` only when a stage genuinely needs ALL of the previous stage first — dedup/merge across the whole set, early-exit on zero, or "compare against the other findings" — because its inter-stage barrier makes every item wait for the slowest peer:
+
+**Python (`eval`, Python backend):**
+
+    phase("Find")
+    found = parallel([lambda d=d: agent(d["prompt"], schema=FINDINGS_SCHEMA) for d in DIMENSIONS])
+    findings = dedupe([f for r in found for f in r["findings"]])   # needs everything at once
+    phase("Verify")
+    verdicts = parallel([lambda f=f: agent(verify_prompt(f), schema=VERDICT_SCHEMA) for f in findings])
+
+**JavaScript (`eval`, JavaScript backend):**
+
+    phase("Find");
+    const found = await parallel(DIMENSIONS.map((d) => async () =>
+        await agent(d.prompt, { schema: FINDINGS_SCHEMA }),
+    ));
+    const findings = dedupe(found.flatMap((r) => r.findings)); // needs everything at once
+    phase("Verify");
+    const verdicts = await parallel(findings.map((f) => async () =>
+        await agent(verifyPrompt(f), { schema: VERDICT_SCHEMA }),
+    ));
+Use ordinary code between calls to flatten/map/filter; don't add a barrier just for that. Nested `parallel()` pools each cap independently, so keep total fan-out sane.
 </structure>
 
 <patterns>
-- **Adversarial verify** — dispatch skeptical reviewers with distinct targets, then keep only findings the parent can verify against source.
-- **Perspective-diverse review** — use separate correctness, security, performance, and maintainability roles instead of identical reviewers.
-- **Completeness critic** — after the first batch, dispatch one read-only critic that asks what modality, file, claim, or proof was missed.
-- **No silent caps** — if you bound coverage (top-N, no retry, sampling), state what was dropped and why before acting.
-- **Parent owns closure** — subagents return evidence; the parent reads it, resolves contradictions, runs proof, and makes the final decision.
+Compose the harness the task calls for:
+- **Adversarial verify** — N independent skeptics per finding, each prompted to REFUTE; keep it only if a majority survive. `votes = parallel([lambda i=i: agent(f"Refute: {claim}. refuted=true if unsure.", schema=VERDICT) for i in range(3)])`, then keep when `sum(not v["refuted"] for v in votes) ≥ 2`.
+- **Perspective-diverse verify** — give each verifier a distinct lens (correctness, security, perf, does-it-reproduce) instead of N identical refuters.
+- **Judge panel** — N attempts from different angles, scored by parallel judges; synthesize from the winner, graft the best of the rest.
+- **Loop-until-dry** — for unknown-size discovery, keep spawning finders until K consecutive rounds surface nothing new; dedup against everything SEEN, not just what was confirmed, or it never converges.
+- **Multi-modal sweep** — parallel finders each searching a different way (by-container, by-content, by-entity, by-time), each blind to the others.
+- **Completeness critic** — a final agent that asks "what's missing — modality not run, claim unverified, file unread?"; its answer is the next round.
+- **Budget/count loops** — Python: `while len(bugs) < 10:`; JavaScript: `while (bugs.length < 10) { … }`. In Python, gate an explicit budget with `budget.total` and `budget.remaining()`; in JavaScript, use `await budget.total()` and `await budget.remaining()`. `log()` each round.
+- **No silent caps** — if you bound coverage (top-N, no-retry, sampling), `log()` what you dropped; silent truncation reads as "covered everything" when it didn't.
+
+Scale to the ask: "find any bugs" → a few finders, single-vote verify. "thoroughly audit / be comprehensive" → larger finder pool, 3–5-vote adversarial pass, a synthesis stage.
 </patterns>
 
 <execution>
-- Capture multi-phase workflow state in the visible todo system when available.
-{{#if taskBatch}}- Batch independent subagents in one `task` call.{{else}}- Dispatch independent subagents as separate `task` calls in the same turn.{{/if}}
-- Give every subagent a narrow target, explicit non-goals, and a concrete return packet.
-- After fan-out returns, read the artifacts, patch or decide, and run the shared gate.
-- Keep going until the task is closed — returned fan-out is a step, not a stopping point.
+- Decompose the surface first; capture it in `todo` when it spans phases.
+- Prefer `schema=` for any agent whose output you branch on.
+- After a fan-out returns, YOU own correctness: read the artifacts, run the gate, verify before acting. Subagents do the legwork; they don't get the last word.
+- Keep going until the task is closed — a returned fan-out is a step, not a stopping point.
 </execution>
 </system-notice>