@arhen/pi-core-subagent 1.3.49 → 1.3.51

package/README.md

@@ -51,12 +51,11 @@ flowchart LR
 - **Proof is an exit code, never a self-report.** Tasks are asked for a runnable `Verify:` command; the leader checks `git diff --stat`. Agents auditing their own work score ~0. ([why](#why-9-is-a-verification-command-not-a-self-report))
 - **No ceremony without edges.** Six independent reviewers stay six independent reviewers — no waves, no gates, no graph vocabulary imposed on flat work.
 - **Agent files respected.** A spawn goal (name + task) that matches a user agent file's `description` (`.agents/agents`, `.claude/agents`, `.pi/agents` — project then home) loads that file — body = system prompt, frontmatter `model`/`tools` apply, file `model` validated against the pi model registry. File wins over inline; no match → on-demand definition.
-- **Two toolsets only.** Read-only (`read, grep, find, ls` — default) or write (`read, grep, find, ls, bash, edit, write` — `write: true`). No per-agent tool config surface.
+- **Two toolsets, plus explicit override.** Read-only (`read, grep, find, ls` — default) or write (`read, grep, find, ls, bash, edit, write` — `write: true`); `tools:` sets an explicit per-task allowlist.
 - **In-process** — children are `AgentSession`s in the same runtime. No process spawn, no context bleed.
-- **Zero parent-context injection.** No catalog, no context hook. 6 slim tools total.
+- **Zero parent-context injection.** No catalog, no context hook. 7 slim tools total.
 - **Throttled updates** — widget/stream updates coalesce to ~6/s; no per-event deep clones.
-- **No silent hangs** — watchdog aborts children that produce no events for 3 minutes.
-- **No default runtime cap** — tasks run until done, stalled (watchdog), or aborted by the user. `maxRuntimeMs` is opt-in (default 0 = unlimited).
+- **Bounded always** — a child is limited only by wall clock: explicit `maxRuntimeMs`, else the 1 h ceiling with `/subagents auto-limit on`, else the 6 h safety ceiling (default).
 
 ## How it runs
 
@@ -308,7 +307,7 @@ Background (default) + intercom — the run returns a runId immediately; you sta
 | `send_agent_message` | message to a sibling subagent's mailbox (`to` = its task id, or `"leader"`) |
 | `poll_agent_messages` | drain this subagent's mailbox |
 
-> **Intercom anti-deadlock:** children are told to never block indefinitely on intercom replies — `ask_parent` keeps the stall watchdog fed while awaiting a parent reply, and sibling polls are capped (~5 tries) with a proceed-with-best-judgment fallback. Gated siblings (later waves) may not be running yet — waiting on them is the top stall cause, so children are instructed not to.
+> **Intercom anti-deadlock:** children are told to never block indefinitely on intercom replies — an unanswered `ask_parent` times out after 10 minutes (the child is told to proceed with best judgment), and sibling polls are capped (~5 tries) with the same fallback. Gated siblings (later waves) may not be running yet — waiting on them is the top stall cause, so children are instructed not to.
 
 ## Commands
 
@@ -352,7 +351,7 @@ The extension has no multiplexer integration and does not want one: it exposes t
 
 ## Context budget
 
-- Parent tools: 6 schemas with short descriptions. **No catalog, no context hook** — nothing injected per request.
+- Parent tools: 7 schemas with short descriptions. **No catalog, no context hook** — nothing injected per request.
 - Background completion: 3-line notice. Full text only via `subagent_result`.
 - Children: isolated sessions; talk tools always injected; each child's prompt states its own task id and its siblings' so mailbox addressing works. Model resolution: explicit `provider/model-id` or bare id via the pi model registry → the parent's current model → settings default. Thinking levels validated against the resolved model's `thinkingLevelMap`.
 

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@arhen/pi-core-subagent",
-	"version": "1.3.49",
+	"version": "1.3.51",
 	"type": "module",
 	"description": "pi extension: fast in-process subagents with a dependency-graph scheduler (needs edges gate tasks and carry upstream output into dependent prompts), plus background runs, intercom and agent-to-agent mailbox. Leader defines agents inline.",
 	"license": "MIT",

package/src/agentfile.ts

@@ -1,9 +1,3 @@
-/** Agent-file resolution — matched by description (goal), not by name.
- *  The model names a subagent with a goal (name + task); user agent files in
- *  `.agents/agents`, `.claude/agents`, `.pi/agents` are scored by token overlap
- *  between their `description` frontmatter and that goal. Best match wins;
- *  ties break by directory priority. A matched file is authoritative (file wins
- *  over inline prompt/model/tools). No match → inline on-demand definition. */
 import { existsSync, readdirSync, readFileSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { parseFrontmatter } from "@earendil-works/pi-coding-agent";
@@ -13,7 +7,6 @@ export interface AgentFileInfo {
 	model?: string;
 	tools?: string[];
 	description?: string;
-	/** The matched file path — surfaced so the leader can audit which file won. */
 	path?: string;
 }
 
@@ -44,10 +37,7 @@ const STOP = new Set([
 	"how",
 	"what",
 	"who",
-	// Pure connectors only. Words like create/user/work/run were stopped here to
-	// kill one false positive and took real routing signal with them (a
-	// scaffolder agent is legitimately "creates", a research agent "user") — the
-	// coverage gate handles weak matches without blinding whole categories.
+
 	"from",
 	"into",
 	"this",
@@ -60,59 +50,35 @@ const STOP = new Set([
 	"other",
 ]);
 
-/** A body becomes the child's ENTIRE system prompt — an oversized reference file
- *  would blow the context window and kill the session with a cryptic error. */
 const MAX_BODY_CHARS = 64_000;
-/** A file takes over the prompt AND the model, so a weak match is expensive.
- *  Both gates must pass: distinct shared terms, and share of the description. */
 const MIN_SHARED_TERMS = 2;
 const MIN_COVERAGE = 0.4;
 
-/** Per-cwd memo of the ancestor walk (project dirs then home), since the files
- *  can't meaningfully change within one run and the walk costs 3 sync stats per
- *  ancestor dir per task otherwise. Keyed per (agentDir + cwd). */
 const walkCache = new Map<string, AgentFileInfo[]>();
 
-/** Test/diagnostic hook: flush the walk cache (files changed mid-session). */
 export function clearAgentFileCache(): void {
 	walkCache.clear();
 }
 
-/** Lowercase, split, drop stopwords, strip plural -s/-es. */
 function tokens(text: string): string[] {
 	return (text.toLowerCase().match(/[a-z0-9]+/g) ?? [])
 		.filter((t) => !STOP.has(t) && t.length > 1)
 		.map((t) => {
 			if (t.endsWith("ing") && t.length > 5) t = t.slice(0, -3);
-			// Only -es after a sibilant is a two-char plural (batches, boxes). Blindly
-			// stripping "es" mangles every -e noun — services→servic vs service→service
-			// never matched, silently breaking the most common routing words.
+
 			if (/(?:ch|sh|ss|x|z|s)es$/.test(t) && t.length > 4) t = t.slice(0, -2);
 			else if (t.endsWith("s") && !t.endsWith("ss") && t.length > 3) t = t.slice(0, -1);
 			return t;
 		});
 }
 
-/**
- * Overlap between the spawn goal and a file's description.
- *
- * Absolute count alone is a bad signal: two shared filler words bound unrelated
- * tasks to whichever agent file happened to share them, and the file then
- * overrode the model too (403s on a plan without that model). Require BOTH a
- * floor of distinct shared terms AND meaningful coverage of the description,
- * so a match means "this file is about that", not "these strings brushed past
- * each other".
- */
 function score(query: string[], desc: string[]): number {
 	if (desc.length === 0) return 0;
 	const q = new Set(query);
 	const shared = new Set<string>();
 	for (const t of desc) if (q.has(t)) shared.add(t);
 	if (shared.size < MIN_SHARED_TERMS) return 0;
-	// Normalize by the SMALLER side. Dividing by the description's length alone
-	// punished well-written descriptions: a 20-token description needed 4 shared
-	// terms while a lazy 3-token one needed 2, so better docs routed worse — and
-	// a 2-word goal could never match a detailed description at all.
+
 	const denom = Math.min(new Set(desc).size, q.size);
 	if (denom === 0 || shared.size / denom < MIN_COVERAGE) return 0;
 	return shared.size;
@@ -150,8 +116,6 @@ function readAgentFile(dir: string): AgentFileInfo[] {
 	return out;
 }
 
-/** Walk cwd's ancestors, then home, returning files in priority order (nearest
- *  first, each dir's 3 subdirs in AGENT_DIRS order). */
 function allAgentFiles(cwd: string, agentDir: string): AgentFileInfo[] {
 	const out: AgentFileInfo[] = [];
 	let dir = cwd;
@@ -161,12 +125,11 @@ function allAgentFiles(cwd: string, agentDir: string): AgentFileInfo[] {
 		if (parent === dir) break;
 		dir = parent;
 	}
-	const home = dirname(dirname(agentDir)); // ~/.pi/agent → ~
+	const home = dirname(dirname(agentDir));
 	for (const sub of AGENT_DIRS) out.push(...readAgentFile(join(home, sub)));
 	return out;
 }
 
-/** Best agent-file match for a spawn goal. Caches per (agentDir, cwd). */
 export function resolveAgentFile(name: string, task: string, cwd: string, agentDir: string): AgentFileInfo | undefined {
 	const query = tokens(`${name} ${task}`);
 	const cacheKey = `${agentDir}${cwd}`;

package/src/child.ts

@@ -1,16 +1,3 @@
-/**
- * Child-session tools.
- *
- * Every child gets four talk tools:
- *   - ask_parent            blocking Q&A with the leader (parent)
- *   - notify_parent         one-way message to the leader
- *   - send_agent_message    one-way message to another subagent's mailbox
- *                           (`to` = target task id in this run, or "leader")
- *   - poll_agent_messages   drain this subagent's mailbox
- *
- * Mailbox is a plain map in the manager; agents talk by polling, not push.
- */
-
 import { StringEnum } from "@earendil-works/pi-ai";
 import type { ToolDefinition } from "@earendil-works/pi-coding-agent";
 import { Type } from "typebox";
@@ -21,9 +8,7 @@ export const CHILD_TALK_TOOLS = ["ask_parent", "notify_parent", "send_agent_mess
 export interface ChildHandlers {
 	onAskParent(taskId: string, question: string): Promise<string>;
 	onNotifyParent(taskId: string, message: string, level: "info" | "warning" | "error"): void;
-	/** Route a child→child message. Returns false when the target is unknown. */
 	onSendMessage(taskId: string, to: string, text: string): boolean;
-	/** Drain the mailbox (returns and clears pending messages). */
 	onPollMailbox(taskId: string): MailboxMessage[];
 }
 
@@ -33,7 +18,7 @@ export function createChildTools(taskId: string, handlers: ChildHandlers): ToolD
 			name: "ask_parent",
 			label: "Ask Parent",
 			description:
-				"Ask the parent agent a clarifying question and BLOCK until it replies. Use sparingly — only when you truly cannot proceed without information only the parent has. Prefer figuring it out yourself.",
+				"Ask the parent agent a clarifying question and BLOCK until it replies (10 min cap — then proceed with best judgment). Use sparingly — only when you truly cannot proceed without information only the parent has. Prefer figuring it out yourself.",
 			promptSnippet: "Ask the parent agent a question when truly blocked.",
 			promptGuidelines: [
 				"Use ask_parent only as a last resort when blocked on information only the parent has.",
@@ -101,7 +86,7 @@ export function createChildTools(taskId: string, handlers: ChildHandlers): ToolD
 				const messages = handlers.onPollMailbox(taskId);
 				if (messages.length === 0) return { content: [{ type: "text" as const, text: "No messages." }], details: {} };
 				const body = messages.map((m) => `from ${m.from}: ${m.text}`).join("\n");
-				const capped = body.length > 4000 ? body.slice(0, 4000).replace(/[\uD800-\uDBFF]$/, "") : body; // multibyte-safe
+				const capped = body.length > 4000 ? body.slice(0, 4000).replace(/[\uD800-\uDBFF]$/, "") : body;
 				return { content: [{ type: "text" as const, text: capped }], details: { messages } };
 			},
 		},

package/src/format.ts

@@ -1,6 +1,3 @@
-/** Rendering: task lines, usage, the widget, summaries, notices.
- *  Pure + theme-aware — no manager state, no pi runtime. */
-
 import type { AssistantMessage } from "@earendil-works/pi-ai";
 import type { Theme } from "@earendil-works/pi-coding-agent";
 import { type Component, truncateToWidth } from "@earendil-works/pi-tui";
@@ -14,13 +11,12 @@ import {
 	type UsageStats,
 } from "./types.ts";
 
-/** Cap on a single child's final output (and on full-run summaries). */
 const FINAL_OUTPUT_CAP = 24 * 1024;
 
 export function truncateText(text: string, max = FINAL_OUTPUT_CAP): string {
 	if (Buffer.byteLength(text, "utf8") <= max) return text;
 	let out = text.slice(0, max);
-	while (Buffer.byteLength(out, "utf8") > max) out = out.slice(0, -1); // multibyte-safe
+	while (Buffer.byteLength(out, "utf8") > max) out = out.slice(0, -1);
 	return `${out}\n\n[Output truncated. Full child session is available in the session file.]`;
 }
 export function getFirstText(message: AssistantMessage): string {
@@ -67,40 +63,24 @@ function taskStatsWithUsage(task: TaskSnapshot): string {
 export function taskLine(task: TaskSnapshot): string {
 	return `${statusIcon(task.status)} ${task.agent} · ${taskStatsWithUsage(task)} · ${taskTimer(task)}`;
 }
-/**
- * Numbers take the theme's number color, everything else stays muted — like the footer.
- * Must run on RAW text: styling an already-colored string rewrites the digits
- * inside the ANSI escape codes themselves ("38;2;139;136;122m16 tools").
- */
 export function colorNums(text: string, theme: Theme): string {
-	// A value keeps its unit: "460.6k" and "2m30s" each color as one token, not digit-by-digit.
 	return text.replace(/((?:\d+(?:\.\d+)?[a-zA-Z]*)+)|([^\d]+)/g, (_m, num?: string, rest?: string) =>
 		num ? theme.fg("syntaxNumber", num) : theme.fg("muted", rest ?? ""),
 	);
 }
-/**
- * Themed one-liner. Finished tasks dim entirely (stats included); live tasks
- * keep the agent name readable with themed numbers.
- */
 function themedTaskLine(task: TaskSnapshot, theme: Theme, activity = ""): string {
 	const tail = `${taskStatsWithUsage(task)} · ${taskTimer(task)}`;
-	// Queued task with unmet needs: show the gate it's waiting on instead of empty stats.
+
 	const gate =
 		task.status === "queued" && task.needs?.length ? `${theme.fg("muted", `↳ waits ${task.needs.join(", ")}`)} · ` : "";
 	if (TERMINAL.includes(task.status)) {
 		return theme.fg("dim", `${statusIcon(task.status)} ${task.agent} · ${tail}`);
 	}
-	// Talking (mailbox/intercom tool in flight): pulse the name accent↔dim; normal otherwise.
+
 	pulsePhase += 1;
 	const name = isTalking(task) ? theme.fg(pulsePhase % 2 === 0 ? "accent" : "dim", `${task.agent} ⇄`) : task.agent;
 	return `${statusIcon(task.status)} ${name} · ${gate}${activity}${colorNums(tail, theme)}`;
 }
-/**
- * Human-readable activity line: "Read src/index.ts", "Grep wrapSingleLine".
- * ponytail: picks the first interesting string arg instead of a per-tool table —
- * unknown/custom tools then read fine too. Add a case only if one reads badly.
- */
-// Order matters: the most specific arg wins (grep's pattern beats its path).
 const ARG_KEYS = ["pattern", "query", "command", "path", "file_path", "filePath", "url", "name", "subject", "task"];
 export function describeCall(toolName: string, args: unknown, cwd?: string): string {
 	const verb = toolName.charAt(0).toUpperCase() + toolName.slice(1);
@@ -112,7 +92,7 @@ export function describeCall(toolName: string, args: unknown, cwd?: string): str
 	}
 	if (value === undefined) return verb;
 	let text = value.replace(/\s+/g, " ").trim();
-	if (cwd && text.startsWith(`${cwd}/`)) text = text.slice(cwd.length + 1); // absolute paths inside the task cwd read as noise
+	if (cwd && text.startsWith(`${cwd}/`)) text = text.slice(cwd.length + 1);
 	return `${verb} ${text.length > 60 ? `${text.slice(0, 60)}…` : text}`;
 }
 export function activitySnippet(text: string): string {
@@ -120,14 +100,12 @@ export function activitySnippet(text: string): string {
 	return flat.length > 90 ? `${flat.slice(0, 90)}…` : flat;
 }
 
-/** Mailbox/intercom tools — while one is the task's last activity, the agent is "talking". */
 const TALK_TOOLS = ["poll_agent_messages", "send_agent_message", "ask_parent", "notify_parent"];
 export function isTalking(task: TaskSnapshot): boolean {
 	const a = task.lastActivity?.toLowerCase() ?? "";
 	return TALK_TOOLS.some((t) => a.startsWith(t));
 }
-let pulsePhase = 0; // flips per render; talking agents alternate between the two name styles
-/** Static compact lines (tool-result stream, subagent_status, /subagents). */
+let pulsePhase = 0;
 export function compactLines(run: RunSnapshot): string[] {
 	const lines: string[] = [];
 	for (const task of run.tasks.slice(0, MAX_TASKS)) {
@@ -136,14 +114,6 @@ export function compactLines(run: RunSnapshot): string[] {
 	if (run.tasks.length > MAX_TASKS) lines.push(`… +${run.tasks.length - MAX_TASKS} more`);
 	return lines;
 }
-/**
- * Above-editor widget, todo-tree style:
- *   ● Subagents (0/1)
- *   ├─ • code-sleuth · 4 tools · 12s
- *   │    → read src/auth.ts
- *   └─ ✓ reviewer · 6 tools · 44s
- * Static icons (no animation); latest activity + tool count + runtime per agent.
- */
 const WIDGET_MAX_LINES = 10;
 
 export class SubagentsWidget implements Component {
@@ -152,13 +122,9 @@ export class SubagentsWidget implements Component {
 		private readonly theme: Theme,
 	) {}
 
-	invalidate(): void {
-		// no cached strings; render() reads live state
-	}
+	invalidate(): void {}
 
 	render(width: number): string[] {
-		// ONE flat tree: every run's tasks concatenated under a single heading.
-		// Whether the model spawned N runs or one tasks[] call, the pane reads the same.
 		const runs = this.getRuns().filter((r) => r.tasks.length > 0);
 		if (runs.length === 0) return [];
 		const total = runs.reduce((n, r) => n + r.tasks.length, 0);
@@ -179,7 +145,7 @@ export class SubagentsWidget implements Component {
 				if (shown >= budget) break outer;
 				shown += 1;
 				const activity = task.lastActivity ? `${this.theme.fg("dim", `→ ${task.lastActivity}`)} · ` : "";
-				// Per-TASK status drives dimming: a finished agent stays dim even while siblings run.
+
 				lines.push(
 					truncateToWidth(`${this.theme.fg("dim", "├─")} ${themedTaskLine(task, this.theme, activity)}`, width, "…"),
 				);
@@ -195,8 +161,6 @@ export class SubagentsWidget implements Component {
 		return lines;
 	}
 }
-/** Blocking-call summary: full text, because the model asked for it. */
-/** Where a write child's edits went: a branch to merge, or straight into the tree. */
 function worktreeLine(task: TaskSnapshot, siblings?: TaskSnapshot[]): string {
 	const parts: string[] = [];
 	if (task.branch) {
@@ -204,15 +168,11 @@ function worktreeLine(task: TaskSnapshot, siblings?: TaskSnapshot[]): string {
 			? ` (${task.changedFiles.length} file(s): ${truncateText(task.changedFiles.join(", "), 160)})`
 			: "";
 		parts.push(`Branch: ${task.branch}${files} — merge with \`git merge --no-ff ${task.branch}\` after review.`);
-		// Stacked branches CONTAIN their upstream, so either merge order gives the
-		// same tree (merging this one pulls the upstream in; the upstream's own merge
-		// is then a no-op). Say that, rather than implying an ordering requirement.
+
 		if (task.stackedOn) {
 			parts.push(`Stacked on ${task.stackedOn} — contains that branch's commits, so merging this one brings both.`);
 		}
-		// Sibling branches are independent, not stacked: overlapping files mean the
-		// second merge is a real 3-way, and non-overlapping-but-coupled edits break
-		// silently. Both are computable from changedFiles, so say so.
+
 		const overlap = (siblings ?? [])
 			.filter((s) => s.id !== task.id && s.branch && !s.stackedOn && !task.stackedOn)
 			.flatMap((s) => (s.changedFiles ?? []).filter((f) => task.changedFiles?.includes(f)).map((f) => `${s.id}:${f}`));
@@ -239,7 +199,6 @@ export function makeSummary(run: RunSnapshot): string {
 	const usage = formatUsage(run.aggregateUsage);
 	if (usage) lines.push(`Usage: ${usage}`);
 	for (const task of run.tasks) {
-		// Edges are named so the leader can compare what it delegated against what came back.
 		const edge = task.needs?.length ? ` (${task.id}, needs ${task.needs.join(", ")})` : ` (${task.id})`;
 		const fileNote = task.agentFile ? ` [${task.agentFile}]` : "";
 		const swap = task.modelNote ? `\nModel: ${task.modelNote}` : "";
@@ -248,12 +207,9 @@ export function makeSummary(run: RunSnapshot): string {
 			`\n## ${task.agent}${edge}${fileNote} ${statusIcon(task.status)}${swap}${tools}${task.error ? `\nError: ${task.error}` : `\n${truncateText(task.finalText || "(no output)")}`}${worktreeLine(task, run.tasks)}`,
 		);
 	}
-	// Ceiling on the WHOLE summary — 16 tasks × 24KB would otherwise flood the parent context.
+
 	return truncateText(lines.join("\n"));
 }
-/** Per-task notice: one task's outcome, small. Full output stays out of parent context. */
-/** Dead on arrival: failed without ever producing assistant text — model/plan/auth/agent-file
- *  level, so every respawn with the same config fails identically. */
 export function isStartupFailure(task: TaskSnapshot, kind: string): boolean {
 	return kind === "failed" && !task.finalText?.trim();
 }
@@ -263,9 +219,7 @@ export function makeTaskNotice(run: RunSnapshot, task: TaskSnapshot, kind: strin
 	const wt = task.branch
 		? ` · branch ${task.branch}${task.changedFiles?.length ? `, ${task.changedFiles.length} file(s)` : ""}`
 		: "";
-	// A matched agent file overrides prompt AND model — on a failure (bad model,
-	// 403, wrong persona) that override is the likeliest cause, so it has to be
-	// in the notice, not only in the run summary the leader may never read.
+
 	const src = task.agentFile ? `\nAgent file: ${task.agentFile}${task.model ? ` (model ${task.model})` : ""}` : "";
 	const swap = task.modelNote ? `\nModel: ${task.modelNote}` : "";
 	const tools = task.toolsNote ? `\nTools: ${task.toolsNote}` : "";
@@ -277,7 +231,6 @@ export function makeTaskNotice(run: RunSnapshot, task: TaskSnapshot, kind: strin
 			: `Use subagent_result(runId: "${run.id}", taskId: "${task.id}") for full output.`,
 	].join("\n");
 }
-/** Notification: 3 lines max. Full output stays out of parent context. */
 export function makeNotice(run: RunSnapshot, kind: string): string {
 	const lines = [
 		`Background subagent run ${run.id} ${kind}: ${run.tasks.filter((t) => t.status === "completed").length}/${run.tasks.length} succeeded.`,

package/src/graph.ts

@@ -1,15 +1,5 @@
-/** Graph Protocol §2/§6: dependency resolution, wave notation, edge payloads,
- *  and the wave-frontier scheduler. Pure logic — no pi imports, easily tested. */
 import type { RunMode } from "./types.ts";
 
-/**
- * Resolve dependency edges (Graph Protocol §2). Returns one id list per task,
- * in input order. Chain mode is just `needs: [previous]`, so both modes run
- * through the same wave scheduler.
- *
- * Throws on unknown ids, self-edges, and cycles — a bad graph must fail before
- * any child is spawned, never halfway through a run.
- */
 export function resolveNeeds(inputs: { id?: string; needs?: string[] }[], mode: RunMode): string[][] {
 	const ids = inputs.map((input, index) => input.id ?? `task_${index + 1}`);
 	const known = new Set(ids);
@@ -22,7 +12,7 @@ export function resolveNeeds(inputs: { id?: string; needs?: string[] }[], mode:
 		}
 		return [...new Set(needs)];
 	});
-	// Kahn's algorithm: if any task never becomes ready, the remainder is a cycle.
+
 	const done = new Set<string>();
 	let progress = true;
 	while (progress) {
@@ -41,13 +31,6 @@ export function resolveNeeds(inputs: { id?: string; needs?: string[] }[], mode:
 	return edges;
 }
 
-/**
- * Graph Protocol §2 notation: `wave1[api ∥ db] → gate → wave2[doc]`.
- *
- * Tolerates half-streamed args: a need pointing at an id that has not arrived yet
- * keeps its task out of the ready set, so the layout settles as the model types.
- * Returns "" when there are no edges — flat fan-out gets no graph vocabulary.
- */
 export function waveNotation(tasks: { id?: string; needs?: string[] }[]): string {
 	if (!tasks.some((t) => t.needs?.length)) return "";
 	const ids = tasks.map((t, i) => t.id ?? `task_${i + 1}`);
@@ -56,23 +39,18 @@ export function waveNotation(tasks: { id?: string; needs?: string[] }[]): string
 	const waves: string[][] = [];
 	while (remaining.length > 0) {
 		const ready = remaining.filter((t) => t.needs.every((n) => settled.has(n)));
-		if (ready.length === 0) break; // cycle, or an upstream id not typed yet
+		if (ready.length === 0) break;
 		waves.push(ready.map((t) => t.id));
 		for (const t of ready) settled.add(t.id);
 		remaining = remaining.filter((t) => !settled.has(t.id));
 	}
-	if (remaining.length > 0) waves.push(remaining.map((t) => t.id)); // show them rather than drop them
+	if (remaining.length > 0) waves.push(remaining.map((t) => t.id));
 	if (waves.length < 2) return "";
 	const full = waves.map((w, i) => `wave${i + 1}[${w.join(" ∥ ")}]`).join(" → gate → ");
-	// Long graphs: keep the shape, drop the names.
+
 	return full.length <= 100 ? full : waves.map((w, i) => `wave${i + 1}[${w.length}]`).join(" → gate → ");
 }
 
-/**
- * Graph Protocol §6: the edge carries the upstream output, not just ordering.
- * Upstream results are prepended verbatim; `{previous}` stays supported so old
- * chain prompts keep working (it expands to the first need's output).
- */
 export function applyUpstream(task: string, needs: string[], outputs: Map<string, string>): string {
 	if (needs.length === 0) {
 		return task.includes("{previous}")
@@ -80,7 +58,7 @@ export function applyUpstream(task: string, needs: string[], outputs: Map<string
 			: task;
 	}
 	const first = outputs.get(needs[0] as string) ?? "";
-	const body = task.replace(/\{previous\}/g, () => first); // replacer fn: no $ corruption
+	const body = task.replace(/\{previous\}/g, () => first);
 	const blocks = needs.map((need) => `## Output of ${need}\n${outputs.get(need) ?? "(no output)"}`);
 	return `${blocks.join("\n\n")}\n\n---\n\n${body}`;
 }
@@ -110,11 +88,6 @@ export interface SkippedTask {
 	needs: string[];
 }
 
-/** Wave-frontier scheduler (Graph Protocol §2 execution). Pure control flow:
- *  the caller owns the settled/output bookkeeping and supplies the per-task
- *  runner, so the loop is testable without spawning children. Tasks whose
- *  needs never produced an output (upstream failed/aborted/canceled) are
- *  skipped, not run. */
 export async function runWaveScheduler<T extends SchedulerTask>(
 	tasks: T[],
 	concurrency: number,
@@ -126,14 +99,12 @@ export async function runWaveScheduler<T extends SchedulerTask>(
 	const skipped: SkippedTask[] = [];
 	while (remaining.length > 0) {
 		const ready = remaining.filter((t) => (t.needs ?? []).every((need) => settled.has(need)));
-		// resolveNeeds() rejects cycles up front, so an empty frontier here means every
-		// remaining task is downstream of one that never settled (canceled mid-run).
+
 		if (ready.length === 0) break;
 		await mapWithConcurrency(ready, concurrency, async (task) => {
 			const index = tasks.indexOf(task);
 			const needs = task.needs ?? [];
-			// An upstream failure means this task's input never existed. Running it anyway
-			// burns a full child session on a prompt with a hole in it.
+
 			const broken = needs.filter((need) => !outputs.has(need));
 			if (broken.length > 0) skipped.push({ id: task.id, needs: broken });
 			else await run(task, index);