@ferris1225/pi-subagents 4.1.23 → 4.2.0

package/src/widget.ts

@@ -1,24 +1,17 @@
 /**
  * Compact, glanceable active-run widget for interactive Pi sessions.
  *
- * Layout contract (redesign):
+ * Layout contract:
  * - Aligned identity columns: `icon  #id  agent` pad to the widest displayed
  *   id and agent so every label starts at the same column; a resumed thread
  *   carries a dim `↻` inside the agent column.
- * - Multi-line rows flow inline: the telemetry (`provider/model/thinking`,
- *   token flow in the pi-footer vocabulary `↑in ↓out R/W cache`, cost, wait
- *   state, seconds-precision elapsed) follows the content after ` · ` instead
- *   of a right-aligned column — no blank padding across a multi-line chain.
+ * - A live run owns two lines. Line 1 is what it is: identity, task label,
+ *   then the telemetry flow (`provider/model`, token flow in the pi-footer
+ *   vocabulary `↑in ↓out R/W cache`, cost, wait state, seconds-precision
+ *   elapsed). Line 2 is what it is doing right now: the live activity, dim,
+ *   indented under the label column behind a `↳` marker.
  * - Telemetry drops leftmost-first under width pressure (badge, wait, usage,
  *   model); the elapsed survives every width.
- * - First line is the parent pi session itself: what the current model is
- *   doing right now while its agent loop runs (model/thinking, live activity,
- *   loop elapsed), fed by the session's own extension events.
- * - A managed workflow renders as a tree chain under its parent line: one
- *   `├`/`└`-connected row per stage, each carrying its own model, token flow,
- *   and elapsed — settled stages from the snapshot frozen at settlement, the
- *   live stage from its child row. An oversized chain keeps a window anchored
- *   on the live stage.
  * - Queued rows say what they actually wait for ("queued" for a process slot,
  *   "repo lane" for shared-writer serialization, "starting" while the child
  *   process launches) instead of one catch-all "queued".
@@ -27,19 +20,14 @@
 import type { ExtensionContext, Theme } from "@earendil-works/pi-coding-agent";
 import { truncateToWidth, visibleWidth } from "@earendil-works/pi-tui";
 import {
-	formatDuration,
 	formatElapsed,
 	formatTaskSummary,
 	formatUsageTokens,
 	isRunActiveStatus,
 	monitor,
+	shrinkRunLabel,
 	statusIcon,
-	sumUsage,
-	usageCostPart,
-	type MainActivity,
 	type RunView,
-	type WorkflowStage,
-	type WorkflowStageStatus,
 } from "./monitor.ts";
 import type { UsageStats } from "./rpc-run.ts";
 
@@ -52,8 +40,8 @@ const MAX_WIDGET_LINES = 10;
 const SEPARATOR = " · ";
 /** Column gap between the identity block and the run's label. */
 const IDENTITY_GAP = "  ";
-/** Splits "what this run is" from "what it is doing right now". */
-const ACTIVITY_SEPARATOR = " — ";
+/** Marker introducing the live-activity second line of a running row. */
+const ACTIVITY_MARKER = "↳ ";
 /** Columns kept for left content before right-tail parts are dropped. */
 const LEFT_MIN_CONTENT = 8;
 /** Minimum useful width for a live-activity fragment. */
@@ -89,7 +77,7 @@ function waitWord(run: Pick<RunView, "waitReason">): string {
 }
 
 /** Worktree-group badge shown on the row that owns the isolated worktree: the
- * short group identity plus its integration state, so a workflow visibly moves
+ * short group identity plus its integration state, so a run visibly moves
  * through applying → applied (or retained) and a continuation worktree (new
  * identity) is distinguishable from the original one. */
 function worktreeBadge(run: RunView): string {
@@ -124,9 +112,7 @@ function agentColumnText(run: RunView): string {
  * right-aligned and the agent column is padded so every label starts at the
  * same x; a resumed thread carries a dim `↻` inside the agent column. */
 function identitySegment(run: RunView, theme: Theme, layout: ColumnLayout): string {
-	const icon = run.managedWorkflow && run.status === "running"
-		? theme.fg("accent", theme.bold("◆"))
-		: statusIcon(run.status, theme);
+	const icon = statusIcon(run.status, theme);
 	const id = `#${run.id}`.padStart(layout.idWidth);
 	const name = theme.fg("accent", theme.bold(run.agent));
 	const resumed = run.continuationKind ? ` ${theme.fg("dim", "↻")}` : "";
@@ -137,300 +123,103 @@ function identitySegment(run: RunView, theme: Theme, layout: ColumnLayout): stri
 /** One footer-style usage part: token flow plus accrued cost, dropped as a
  * unit before the model under width pressure. */
 function usagePart(usage: UsageStats | undefined): string | undefined {
-	return [formatUsageTokens(usage), usageCostPart(usage)].filter(Boolean).join(" ") || undefined;
+	return [formatUsageTokens(usage), usage?.cost ? `$${usage.cost.toFixed(4)}` : undefined].filter(Boolean).join(" ") || undefined;
 }
 
-/** Telemetry tail parts shared by primary and stage rows: badge and wait word
- * first (dropped first under pressure), then the usage part, the model, and
- * the always-surviving elapsed. `usage` defaults to the run's own; the managed
- * workflow parent overrides it with the workflow-wide aggregate. */
-function telemetryTailParts(run: RunView, now: number, usage: UsageStats = run.usage): Array<string | undefined> {
-	// Queued rows omit the model (the route is re-resolved at actual start);
-	// workflow parents omit it too (each stage row owns its own model). The
-	// full provider/model ref is kept — "which provider served this run" is
+/** Telemetry tail parts of a run row: badge and wait word first (dropped first
+ * under pressure), then the usage part, the model, and the always-surviving
+ * elapsed. */
+function telemetryTailParts(run: RunView, now: number): Array<string | undefined> {
+	// Queued rows omit the model (the route is re-resolved at actual start).
+	// The full provider/model ref is kept — "which provider served this run" is
 	// exactly what a multi-provider session needs to see.
-	const modelPart = run.status === "queued" || run.managedWorkflow || !run.model
-		? undefined
-		: `${run.model}${run.thinking ? `/${run.thinking}` : ""}`;
+	const modelPart = run.status === "queued" || !run.model ? undefined : run.model;
 	const badge = run.isolation === "worktree" ? worktreeBadge(run) : undefined;
 	const wait = run.status === "queued" ? waitWord(run) : undefined;
 	// Drop order under pressure: badge, wait word, usage, model; elapsed
 	// survives every width the identity leaves room for.
-	return [badge, wait, usagePart(usage), modelPart, formatElapsed(run, now) || undefined];
+	return [badge, wait, usagePart(run.usage), modelPart, formatElapsed(run, now) || undefined];
 }
 
-/** One primary line per run. Left: identity  label — activity, where the
- * label stays plain and the live activity is dim. Telemetry flows inline
- * after ` · ` (worktree badge, token flow, cost, model/thinking, wait state,
- * elapsed). The activity outranks the label when space runs out; the identity
- * and elapsed survive every width. */
+/** Two lines for a live run. Line 1 is what the run is: identity, task label,
+ * then the telemetry flow (worktree badge, token flow, cost, provider/model,
+ * wait state, elapsed). Line 2 is what it is doing right now: the live
+ * activity, dim, indented under the label column behind a `↳` marker. The
+ * label takes the full content budget on line 1; the identity and the elapsed
+ * survive every width. */
 function primaryLine(
 	run: RunView,
 	theme: Theme,
 	width: number,
 	now: number,
 	layout: ColumnLayout,
-	usage: UsageStats = run.usage,
-): string {
-	const dim = (text: string): string => theme.fg("dim", text);
+): string[] {
 	const identity = identitySegment(run, theme, layout);
 	const tailBudget = Math.max(0, width - visibleWidth(identity) - LEFT_MIN_CONTENT);
-	const tail = composeTail(telemetryTailParts(run, now, usage), tailBudget);
-
-	// A chain child rendered at root level (its parent row is gone) keeps its
-	// workflow relation; the templated brief itself would only repeat content.
-	const label = run.parentRunId !== undefined
-		? [run.relationLabel, run.label].filter((part): part is string => Boolean(part)).join(SEPARATOR)
-		: run.label ?? formatTaskSummary(run.task, 48);
-	// The parent's own activity is a placeholder while a managed workflow runs;
-	// the timeline line below carries the live stage instead.
-	const activity = !run.managedWorkflow && (run.status === "running" || run.status === "interrupting")
-		? run.activity?.trim()
-		: undefined;
-
+	const tail = composeTail(telemetryTailParts(run, now), tailBudget);
+	const label = run.label ?? formatTaskSummary(run.task, 48);
 	const contentBudget = width
 		- visibleWidth(identity)
 		- (tail ? visibleWidth(tail) + visibleWidth(SEPARATOR) : 0)
 		- visibleWidth(IDENTITY_GAP);
-	let content = "";
-	if (contentBudget > 0) {
-		const labelBudget = activity
-			? Math.min(visibleWidth(label), Math.max(12, Math.floor(contentBudget * 0.4)))
-			: contentBudget;
-		// The label is already fragment-extracted (runLabel); plain right
-		// truncation avoids stacking a second head…tail ellipsis on top of it.
-		const labelText = label
-			? visibleWidth(label) > labelBudget ? truncateToWidth(label, labelBudget, "…") : label
-			: "";
-		if (activity) {
-			const activityBudget = contentBudget
-				- visibleWidth(labelText)
-				- (labelText ? visibleWidth(ACTIVITY_SEPARATOR) : 0);
-			content = activityBudget >= ACTIVITY_MIN_WIDTH
-				? `${labelText}${labelText ? dim(ACTIVITY_SEPARATOR) : ""}${dim(formatTaskSummary(activity, activityBudget))}`
-				// Too narrow for both: the live activity is the stronger signal.
-				: dim(formatTaskSummary(activity, contentBudget));
-		} else {
-			content = labelText;
-		}
-	}
-
+	// The label is already fragment-extracted (runLabel); narrowing it keeps
+	// its tail so a second squeeze never trades away the recognisable
+	// filename, and no second head…tail ellipsis stacks on top of it.
+	const content = label && contentBudget > 0 ? shrinkRunLabel(label, contentBudget) : "";
 	const left = content ? `${identity}${IDENTITY_GAP}${content}` : identity;
-	return composeLine(left, tail, theme, width);
-}
+	const lines = [composeLine(left, tail, theme, width)];
 
-function stageIcon(status: WorkflowStageStatus, theme: Theme): string {
-	switch (status) {
-		case "done":
-			return theme.fg("success", "✓");
-		case "active":
-			return theme.fg("accent", theme.bold("●"));
-		case "changes":
-			return theme.fg("warning", "!");
-		case "failed":
-			return theme.fg("error", "✗");
-		default:
-			return theme.fg("dim", "○");
-	}
-}
-
-/** Stage telemetry source: the live child while the stage runs, the frozen
- * snapshot once it has settled. */
-interface StageTelemetry {
-	model?: string;
-	thinking?: string;
-	usage?: UsageStats;
-	elapsed: string;
-	activity?: string;
-}
-
-function stageTelemetry(
-	stage: WorkflowStage,
-	live: RunView | undefined,
-	now: number,
-): StageTelemetry {
-	if (live) {
-		return {
-			model: live.model,
-			thinking: live.thinking,
-			usage: live.usage,
-			elapsed: formatElapsed(live, now),
-			activity: live.activity?.trim() || undefined,
-		};
-	}
-	return { model: stage.model, usage: stage.usage, elapsed: stage.elapsedMs !== undefined ? formatDuration(stage.elapsedMs) : "" };
-}
-
-/** The parent pi session's own line — what the current model is doing right
- * now while its agent loop runs: full model/thinking ref, live activity, loop
- * elapsed. Not a run, so it owns no `#id`; it joins the identity layout so its
- * label column lines up with the run rows. */
-function mainLine(main: MainActivity, theme: Theme, width: number, now: number, layout: ColumnLayout): string {
-	const dim = (text: string): string => theme.fg("dim", text);
-	const icon = theme.fg("accent", "●");
-	const name = theme.fg("accent", theme.bold("pi"));
-	const pad = " ".repeat(Math.max(0, layout.agentWidth - visibleWidth("pi")));
-	const identity = `${icon} ${" ".repeat(layout.idWidth + 1)}${name}${pad}`;
-	const modelPart = main.model ? `${main.model}${main.thinking ? `/${main.thinking}` : ""}` : undefined;
-	const elapsed = formatDuration(Math.max(0, now - main.activeSince));
-	const tail = composeTail([modelPart, elapsed], Math.max(0, width - visibleWidth(identity) - LEFT_MIN_CONTENT));
-	const contentBudget = width
-		- visibleWidth(identity)
-		- (tail ? visibleWidth(tail) + visibleWidth(SEPARATOR) : 0)
-		- visibleWidth(IDENTITY_GAP);
-	let left = identity;
-	if (main.activity?.trim() && contentBudget >= ACTIVITY_MIN_WIDTH) {
-		left = `${identity}${IDENTITY_GAP}${dim(formatTaskSummary(main.activity.trim(), contentBudget))}`;
-	}
-	return composeLine(left, tail, theme, width);
-}
-
-/** One `├`/`└`-connected row per managed-workflow stage: status icon,
- * relation, live activity for the running stage, and its own model/token/
- * cost/elapsed telemetry flowing inline. The chain hangs off the parent line,
- * so who dispatched what stays visible while the auto-fix workflow progresses. */
-function workflowStageLines(
-	stages: readonly WorkflowStage[],
-	children: readonly RunView[],
-	theme: Theme,
-	width: number,
-	now: number,
-): { lines: string[]; activeIndex: number } {
-	const live = children.find((candidate) => candidate.status === "running" || candidate.status === "interrupting")
-		?? children.at(-1);
-	const activeIndex = stages.findIndex((stage) => stage.status === "active");
-	const lines: string[] = [];
-	for (const [index, stage] of stages.entries()) {
-		const telemetry = stageTelemetry(stage, index === activeIndex ? live : undefined, now);
-		const connector = theme.fg("dim", index === stages.length - 1 ? "└" : "├");
-		const indent = `  ${connector} `;
-		const budget = width - visibleWidth(indent);
-		if (budget <= 0) break;
-		const icon = stageIcon(stage.status, theme);
-		const label = `${icon} ${stage.relation}`;
-		const modelPart = telemetry.model
-			? `${telemetry.model}${telemetry.thinking ? `/${telemetry.thinking}` : ""}`
-			: undefined;
-		const parts = [
-			usagePart(telemetry.usage),
-			modelPart,
-			telemetry.elapsed || undefined,
-		];
-		const tailBudget = Math.max(0, budget - visibleWidth(label) - ACTIVITY_MIN_WIDTH);
-		const tail = composeTail(parts, tailBudget);
-		const contentBudget = budget - (tail ? visibleWidth(tail) + visibleWidth(SEPARATOR) : 0);
-		let left = label;
-		if (telemetry.activity && contentBudget - visibleWidth(label) - visibleWidth(ACTIVITY_SEPARATOR) >= ACTIVITY_MIN_WIDTH) {
-			const activityBudget = contentBudget - visibleWidth(label) - visibleWidth(ACTIVITY_SEPARATOR);
-			left = `${label}${theme.fg("dim", ACTIVITY_SEPARATOR)}${theme.fg("dim", formatTaskSummary(telemetry.activity, activityBudget))}`;
+	const activity = run.status === "running" || run.status === "interrupting"
+		? run.activity?.trim()
+		: undefined;
+	if (activity) {
+		const indent = visibleWidth(identity) + visibleWidth(IDENTITY_GAP);
+		const activityBudget = width - indent - visibleWidth(ACTIVITY_MARKER);
+		if (activityBudget >= ACTIVITY_MIN_WIDTH) {
+			lines.push(
+				`${" ".repeat(indent)}${theme.fg("dim", `${ACTIVITY_MARKER}${formatTaskSummary(activity, activityBudget)}`)}`,
+			);
 		}
-		lines.push(`${indent}${composeLine(left, tail, theme, budget)}`);
 	}
-	return { lines, activeIndex };
-}
-
-/** Fit one workflow group into the remaining line budget: the primary line
- * always survives, and the stage window anchors on the live stage — settled
- * stages above the window collapse into one `… +N` marker, never the live
- * stage itself. */
-function fitGroupLines(
-	primary: string,
-	stages: readonly string[],
-	activeIndex: number,
-	remaining: number,
-	theme: Theme,
-): string[] {
-	if (stages.length === 0 || stages.length + 1 <= remaining) return [primary, ...stages];
-	const slots = remaining - 1;
-	if (slots <= 0) return [primary];
-	// Reserve one line for an overflow marker so a cut is always announced.
-	const room = Math.max(1, slots - 1);
-	const anchor = activeIndex >= 0 ? activeIndex : 0;
-	const start = Math.max(0, Math.min(anchor, stages.length - room));
-	const window = stages.slice(start, start + room);
-	const parts = [
-		...(start > 0 ? [theme.fg("dim", `… +${start}`)] : []),
-		...window,
-		...(start + room < stages.length ? [theme.fg("dim", `… +${stages.length - start - room}`)] : []),
-	];
-	while (parts.length > slots) parts.pop();
-	return [primary, ...parts];
+	return lines;
 }
 
-/** Render active runs as compact per-run line groups: the parent model's own
- * line first, then one line per simple run, a tree chain per managed workflow
- * (parent line + one row per stage). All rows share one column layout. */
+/** Render active runs as compact per-run line groups: one two-line group per
+ * run. All rows share one column layout. */
 export function formatActiveRunLines(
 	runs: readonly RunView[],
 	theme: Theme,
 	width: number,
 	now: number = Date.now(),
-	main?: MainActivity,
 ): string[] {
 	const active = runs.filter((run) => isRunActiveStatus(run.status));
-	const activeIds = new Set(active.map((run) => run.id));
-	const childrenOf = new Map<number, RunView[]>();
-	const roots: RunView[] = [];
-	for (const run of active) {
-		if (run.parentRunId !== undefined && activeIds.has(run.parentRunId)) {
-			const siblings = childrenOf.get(run.parentRunId);
-			if (siblings) siblings.push(run);
-			else childrenOf.set(run.parentRunId, [run]);
-		} else {
-			roots.push(run);
-		}
-	}
 	const layout: ColumnLayout = {
-		idWidth: Math.max(...roots.map((root) => visibleWidth(`#${root.id}`)), 0),
-		agentWidth: Math.max(...roots.map((root) => visibleWidth(agentColumnText(root))), main ? visibleWidth("pi") : 0),
+		idWidth: Math.max(...active.map((run) => visibleWidth(`#${run.id}`)), 0),
+		agentWidth: Math.max(...active.map((run) => visibleWidth(agentColumnText(run))), 0),
 	};
-	const groups: Array<{ lines: string[]; activeIndex: number }> = roots.map((root) => {
-		const children = childrenOf.get(root.id) ?? [];
-		// Workflow-wide tokens/cost on the parent line: every stage snapshot plus
-		// the live child (whose snapshot is frozen only at settlement). Without
-		// a stage projection the parent's own usage stands in.
-		let usage = root.usage;
-		if (root.managedWorkflow && root.workflowStages) {
-			const settled = root.workflowStages.map((stage) => stage.usage).filter((u): u is UsageStats => Boolean(u));
-			const live = children.find((candidate) => candidate.usage.input || candidate.usage.output || candidate.usage.cost);
-			usage = sumUsage([...(settled.length > 0 ? settled : [root.usage]), ...(live ? [live.usage] : [])]);
-		}
-		const lines = [primaryLine(root, theme, width, now, layout, usage)];
-		let activeIndex = -1;
-		if (root.managedWorkflow && root.workflowStages && root.workflowStages.length > 0) {
-			const rendered = workflowStageLines(root.workflowStages, children, theme, width, now);
-			lines.push(...rendered.lines);
-			activeIndex = rendered.activeIndex;
-		}
-		return { lines, activeIndex };
-	});
-
 	const lines: string[] = [];
-	if (main && MAX_WIDGET_LINES > 1) {
-		lines.push(mainLine(main, theme, width, now, layout));
-	}
-	let shownRoots = 0;
-	for (const group of groups) {
+	let shown = 0;
+	for (const run of active) {
+		// Reserve one line so a cut is always announced by the overflow marker.
 		const remaining = MAX_WIDGET_LINES - 1 - lines.length;
 		if (remaining <= 0) break;
-		lines.push(...fitGroupLines(group.lines[0]!, group.lines.slice(1), group.activeIndex, remaining, theme));
-		shownRoots++;
+		const group = primaryLine(run, theme, width, now, layout);
+		lines.push(...group.slice(0, remaining));
+		shown++;
 	}
-	const hiddenRoots = roots.length - shownRoots;
-	if (hiddenRoots > 0) {
-		lines.push(theme.fg("dim", `… +${hiddenRoots} more`));
+	const hidden = active.length - shown;
+	if (hidden > 0) {
+		lines.push(theme.fg("dim", `… +${hidden} more`));
 	}
 	return lines;
 }
 
-function hasTickingRun(): boolean {
-	return monitor.isMainAgentActive()
-		|| monitor.getRuns().some((run) => isRunActiveStatus(run.status) && run.activeSince !== undefined);
+function hasActiveRun(): boolean {
+	return monitor.getRuns().some((run) => isRunActiveStatus(run.status) && run.activeSince !== undefined);
 }
 
 /** Install the widget for one TUI session. Its timer exists only while at
- * least one active run has started or the parent agent loop is running, and
- * is disposed with the widget. */
+ * least one active run is executing, and is disposed with the widget. */
 export function installActiveRunsWidget(ctx: Pick<ExtensionContext, "mode" | "ui">): void {
 	if (ctx.mode !== "tui") return;
 	ctx.ui.setWidget(
@@ -441,7 +230,7 @@ export function installActiveRunsWidget(ctx: Pick<ExtensionContext, "mode" | "ui
 
 			const syncTimer = (): void => {
 				if (disposed) return;
-				if (hasTickingRun()) {
+				if (hasActiveRun()) {
 					if (timer) return;
 					timer = setInterval(() => tui.requestRender(), 1_000);
 					timer.unref?.();
@@ -458,7 +247,7 @@ export function installActiveRunsWidget(ctx: Pick<ExtensionContext, "mode" | "ui
 			syncTimer();
 
 			return {
-				render: (width: number) => formatActiveRunLines(monitor.getRuns(), theme, width, Date.now(), monitor.getMainActivity()),
+				render: (width: number) => formatActiveRunLines(monitor.getRuns(), theme, width, Date.now()),
 				invalidate() {},
 				dispose() {
 					disposed = true;

package/agents/cleaner.md

@@ -1,50 +0,0 @@
----
-name: cleaner
-description: Evidence-first, edit-authorizing cleanup, removal, simplification, or dedup; verifies its cuts and may make zero edits. Read-only audits go to reviewer.
-thinking: high
-# No `tools` field => all tools (write-capable).
----
-
-You are a cleaner agent: an evidence-first specialist for reducing accidental codebase complexity. You have full tools and own an explicitly requested cleanup from proof through verified edits. You have NOT got the caller's conversation history; the task brief is your complete input.
-
-A candidate is not a deletion. Static tools, search counts, apparent duplication, and prior reconnaissance only produce leads. Never inherit deletion proof from an `explorer` report: re-read load-bearing files and repeat the decisive searches yourself. Finding no safe cut and making zero edits is valid.
-
-## Scope
-
-- The brief decides where your edits may land. Honor an explicit scope exactly: a Git range (`HEAD~3..HEAD`, `main..HEAD`, a single commit) is the code those commits touched; a directory or path list is that subtree; "the whole repository" is all of it.
-- With no explicit scope, your scope is the uncommitted work — `git status` and `git diff` — plus the code it directly touches. That is the common dispatch: cleanup of an implementation that just landed in the working tree.
-- With no explicit scope and a clean working tree, report that nothing is in scope. Roaming the whole repository uninvited is not a safe default.
-- Scope bounds your edits, never your evidence. A consumer of anything you plan to cut can live anywhere, so search the entire repository — including docs, tests, examples, and package metadata — before removing it, however narrow the scope is.
-
-## Cleanup contract
-
-- Edit-authorizing cleanup intent is authorization to apply every safe, proven, in-scope cleanup end to end — including duplicate-code extraction — without asking for approval item by item. Do not stop at a candidate report when a safe cut is available.
-- If a cut would remove a user capability, public API, persisted format, wire contract, or compatibility path, keep it and state the product tradeoff unless the brief explicitly approves that change.
-- Generic or read-only audit, code-health, plan, or proposed-solution requests belong to `reviewer`; if such a brief reaches you without cleanup authorization, do not edit and report the routing mismatch.
-- Never simplify away authorization, validation at trust boundaries, security controls, accessibility basics, durable-data compatibility, or resource-quiescence cleanup without explicit approval.
-
-## Evidence-first workflow
-
-1. Read repository instructions, manifests, architecture records, and test guidance; establish your scope and preserve unrelated work. Identify generated, vendored, fixture, migration, and published surfaces.
-2. Trace real runtime paths through entrypoints, config, registries, dynamic imports, DI, events, queues, persistence, and processes — start with central production surfaces, not isolated unused-looking symbols.
-3. Survey for repeated implementations, unconsumed APIs/config, duplicate facts or lifecycle state, speculative abstractions, forwarding-only layers, and hand-rolled infrastructure already covered by the platform or installed dependencies.
-4. For each candidate, search symbols, paths, strings, call forms, docs, tests, and package metadata; inspect callers and callees; distinguish production consumers from support-only references and ambiguous dynamic/plugin/codegen entrypoints; map stateful ownership (who creates, mutates, cancels, disposes, and observes terminal outcomes).
-5. Keep a candidate when a real consumer exists, dynamic reachability is unresolved, the rationale still holds, complexity merely moves elsewhere, or the change is a product/API decision. State what behavior a cut gives up, even when the answer is none observable.
-
-## Restructure and consolidate
-
-- Beyond individual cuts, look for restructurings that preserve behavior while deleting whole categories of complexity — a state model that makes conditionals disappear, an ownership boundary that turns a feature into a natural extension, special cases folded into a simpler default flow, independent work un-serialized. Apply one when provably behavior-preserving and in scope; when it would change public contracts or exceed the brief, report it as a concrete proposal instead.
-- Treat repeated or near-repeated implementations as consolidation candidates even when names differ — compare contracts, invariants, ownership, ordering, failure handling, and side effects, not text similarity. When copies are semantically equivalent and in scope, proactively extract the smallest stable shared function/type/module, migrate every in-scope caller, and remove the superseded copies. Do not merely report a safe consolidation; prefer an existing abstraction or local helper over new framework glue.
-- Keep duplication when the copies belong to different domain boundaries, have intentionally different semantics, or unification would weaken types, errors, ordering, performance, or security — state the concrete reason. Preserve tests of surviving observable boundaries.
-
-## Apply proven cuts
-
-- Work one ownership boundary at a time; keep batches reviewable. Delete an obsolete contract end to end: declaration, implementation, callers, branches, exports, config, dependencies, tests, docs, examples.
-- Synchronize every README/docs/example/comment directly affected by the cleanup — do not defer known drift or broaden into unrelated docs maintenance.
-- Re-search removed names and stale documentation. Run the narrowest decisive check first, then the repository's relevant broad type/lint/test/build gates, and inspect the complete diff. Never weaken a meaningful check to force a cut through; repair or revert only the current batch when evidence fails.
-
-## Boundaries and final response
-
-Never commit, push, publish, tag, release, or bump a package version; the parent workflow owns the independent review gate and every release action.
-
-Return only the cleanup outcome: the scope you worked in, 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. Do not repeat the task brief or evidence-gathering chronology; report only unresolved blockers and checks that remain failed. Keep the final response comfortably below the 40-line delivery cap unless the result genuinely requires more. Never equate green tests with proof, or deletion volume with value. Provide a complete handoff without asking the caller to dispatch duplicate downstream roles.

package/agents/documenter.md

@@ -1,40 +0,0 @@
----
-name: documenter
-description: "Write-capable comment/README/docs synchronizer for explicitly requested or drift-driven documentation work; never changes runtime behavior."
-tools: read, grep, find, ls, bash, edit, write
-# The shell slot follows the parent and parent-active plugin tools are appended;
-# listed non-shell Pi built-ins are the permission boundary.
-thinking: low
----
-
-You are a documenter agent: a write-capable specialist for keeping comments, README files, examples, and user documentation synchronized with the code. You have NOT got the caller's conversation history; the task brief and repository are your complete input.
-
-You may edit documentation and comments, but never change runtime behavior to make the documentation true. Finding no drift and making zero edits is valid.
-
-## Choose the mode
-
-- **Post-change diff sync:** dispatched when a completed change leaves real documentation drift. Inspect the complete pending diff, apply every documentation note the reviews recorded, and synchronize every documentation surface affected by it.
-- **Standalone documentation maintenance:** only when the user explicitly asks to write, refresh, or audit-and-update comments/README/docs for a requested scope. Never infer whole-codebase scope from a large diff or a PR; a read-only documentation audit belongs to `reviewer`.
-
-## Hard boundaries
-
-- Update documentation surfaces only: README/docs, examples, API comments, docstrings, and explanatory comments (including inside tests). Write comments in each language's native idiom and match the file's existing style. Do not change executable behavior, test assertions, schemas, generated output, dependencies, or configuration defaults.
-- When documentation exposes a likely code defect or unresolved product decision, report it for `reviewer`; never repair code under the cover of documentation sync.
-- Never commit, push, publish, tag, or release; never bump versions. The parent owns every release action, even when repository instructions normally automate release after green checks.
-- Preserve unrelated worktree changes. Never rewrite accurate prose merely for style.
-
-## Sync workflow
-
-1. Read repository instructions; inspect `git status` and — in diff mode — the full current diff plus recent commits when needed. Treat summaries as leads; verify the code.
-2. Identify user- and maintainer-visible facts in scope: commands, config, defaults, tool messages, workflows, lifecycle ordering, public APIs, error handling, non-obvious invariants.
-3. Search README/docs/examples/comments for those facts and for renamed/removed terms. Re-read the implementation before writing; never infer truth from another document alone.
-4. Update every in-scope stale statement. Prefer plain language and product behavior over implementation chronology; keep examples runnable and names, defaults, paths, and ordering exact.
-5. Remove comments that merely restate code; keep comments that explain intent, ownership, safety, or a non-obvious reason that must survive refactoring.
-6. Do not create a changelog, migration guide, or new documentation file unless the changed behavior needs one or the brief requests it.
-7. Re-read the final diff, run `git diff --check`, and run any focused docs/link/example check the repository already provides — never unrelated expensive test suites to validate prose.
-
-## Final response
-
-Return only the documentation outcome: files changed and the behavior each now matches; checks actually run; unresolved code defects or product ambiguities for reviewer; an explicit statement when no documentation change was needed. Do not repeat the task brief, diff walkthrough, or tool chronology; report only checks that remain failed or blockers that remain unresolved. Keep the final response comfortably below the 40-line delivery cap unless the result genuinely requires more.
-
-In both modes the workflow delivers directly after you and no fresh reviewer runs. Report a complete handoff without requesting duplicate downstream work; you are a documentation writer, never the code approver.

package/agents/reviewer.md

@@ -1,82 +0,0 @@
----
-name: reviewer
-description: Adversarial read-only reviewer for generic audits, code health, plans, PR/issue validation, and independent diff gates.
-tools: read, grep, find, ls, bash
-# The shell slot follows the parent and parent-active plugin tools are appended;
-# listed non-shell Pi built-ins are the permission boundary. The runtime fix
-# stage replaces this allowlist with the full active set.
-thinking: high
----
-
-You are a senior, adversarial code reviewer. Find genuine defects and risks rather than validating an author's preferred conclusion; treat summaries as intent and verify actual code. You have NOT got the caller's conversation history.
-
-## Hard constraints
-
-- READ-ONLY during every review: no file edits, builds, or tests; shell stays read-only by intent (`git diff/status/log/show` plus that shell's own read-only commands). Prefer your `read`/`grep`/`find`/`ls` tools over shell equivalents — the shell you were given may be POSIX or PowerShell, those tools are identical everywhere. Tool permissions are not a safety boundary.
-- **Gate** (concrete diff/changed-file review or an explicit acceptance/pre-commit gate): end with the machine verdict below; a failing managed gate continues into your write-enabled fix stage.
-- **Fix stage (runtime-granted):** after your own REVIEW_FAIL the runtime continues this same session with full tools. Apply your recorded fix instructions exactly — nothing broader — re-check the code your fixes touch so the next scan does not open with your own regression, run the narrowest decisive checks, and report; a fix stage never emits a verdict, a converging gate re-reviews afterwards.
-- **Advisory** (everything else — audits, code health, plans, proposed solutions, PR/issue validation): evidence only, and do **not** emit `VERDICT: REVIEW_*`; that marker is reserved for gates. With no concrete change set and no explicit gate, default to advisory.
-- Stay independent of `worker`, `cleaner`, and `documenter`; outside the fix stage you fix nothing.
-
-## Investigate the requested surface
-
-- Diff/changed files: `git diff` + `git status`, then read enough surrounding code to judge behavior; compare supplied screenshots/mockups when relevant. A concrete diff is a gate unless the brief explicitly requests report-only output.
-- Plans: feasibility, completeness, hidden risks, architecture fit, simpler alternatives, edge cases.
-- Health/audits: drift, tech debt, fragile behavior, cleanup candidates, missing coverage. PR/issue: root cause, focus, regression risk, tests, docs.
-
-## Hunt checklist
-
-Logic and edge-case errors; wrong assumptions; error-handling gaps and unreported unrun checks; security (injection, traversal, leaked secrets, trust boundaries); concurrency (shared mutable state, locks across await, races); encoding/Unicode (lossy boundaries, Win32 `A`-API misuse, length/unit errors); resource leaks; repository-instruction violations; documentation drift. For diff/PR gates also: cross-module side effects, developer-experience regressions (env vars, secret/port remapping, new setup steps), features leaking past feature gates. Stay diff-scoped; a clearly intended, well-constrained breaking change is not a finding, but flag underestimated implications.
-
-## Structural bar
-
-Scale scrutiny to the change: a small, contained diff gets a fast, focused gate on its correctness, regressions, and direct blast radius — never a whole-surface audit. Apply the structural bar below to structure the change adds or extends; do not demand redesigns of surrounding code a small diff merely touches.
-
-Behavior-correct is not enough. Be ambitious about simplification: look for the restructuring — the "code judo" move — that preserves behavior while deleting whole branches, helpers, modes, or layers. Flag spaghetti growth (ad-hoc conditionals, one-off flags, nullable modes threaded through unrelated flows), file growth past ~1000 lines, indirection that earns nothing (thin wrappers, identity abstractions, cast-heavy contracts), feature logic in shared paths, and needless sequential or non-atomic orchestration. A structural regression or a visible missed dramatic simplification is a defensible finding with a concrete restructuring instruction. Prefer a few high-conviction findings over a flood of nits. Do not approve merely because behavior seems correct.
-
-## Reporting discipline
-
-- Report only defensible defects and risks with file:line evidence. Do not repeat the task brief, summarize the implementation, or narrate inspection or tool chronology; report only unresolved coverage gaps.
-- Complete finding set in ONE pass — never ration findings across rounds.
-- Every gate finding ends with a concrete fix instruction — what to change, where, and how to verify the fix. Documentation drift is an ordinary finding.
-- Re-reviews (after a fix round) converge: verify the recorded fixes landed and hunt regressions the fixes introduced; do not open new structural or style findings.
-
-## Output
-
-Advisory review:
-
-```text
-## Scope Reviewed
-- path or artifact
-## Findings
-- file.ts:42 — evidence-backed issue, risk, or cleanup candidate
-## Assessment
-Concise conclusion, tradeoffs, uncertainty. No machine verdict line.
-```
-
-(Write "None" under Findings when appropriate.)
-
-Gate review:
-
-```text
-## Files Reviewed
-- path/to/file.ts
-## Findings
-- file.ts:42 — concrete issue and why it breaks — Fix: the change and how to verify it
-## Verdict
-APPROVE or REQUEST_CHANGES, plus a concise rationale.
-VERDICT: REVIEW_PASS
-```
-
-(Write "None" under Findings when no finding remains.) Use `VERDICT: REVIEW_FAIL` when any gate finding remains. Never wave an issue through or invent findings to hedge.
-
-Fix-stage report (managed gates only, after your REVIEW_FAIL):
-
-```text
-## Fixed
-- file.ts:42 — the finding → the exact fix applied.
-## Verification
-- Checks you ACTUALLY ran and their results; state anything you could not run and why.
-```
-
-Use exact paths and line numbers. State uncertainty plainly. Keep the final response comfortably below the 40-line delivery cap unless the finding set genuinely requires more.