@juicesharp/rpiv-pi 0.12.2 → 0.12.3

package/extensions/subagent-widget/constants.ts

@@ -16,11 +16,19 @@ export const ERROR_STATUSES: ReadonlySet<ErrorStatus> = new Set<ErrorStatus>([
 	"stopped",
 ]);
 
-/** How many turns a completed run lingers before it drops from the tree. */
-export const COMPLETED_LINGER_TURNS = 1;
+/** How many turns a completed run lingers before it drops from the tree.
+ * Advanced by both user-input boundaries (`pi.on("input")`) and orchestrator
+ * agent-loop iterations (`pi.on("turn_start")`), so completed runs stay visible
+ * for ~3 orchestrator turns after the last agent finishes, then auto-evict. */
+export const COMPLETED_LINGER_TURNS = 3;
 
 /** How many turns an error/aborted/steered/stopped run lingers. */
-export const ERROR_LINGER_TURNS = 2;
+export const ERROR_LINGER_TURNS = 5;
 
 /** Spinner animation tick in ms. TUI's 16 ms render coalescing absorbs this. */
 export const TICK_MS = 80;
+
+/** Max visible characters of the descriptor column (task text). Applied
+ * identically to running + finished rows so the stats tail is never
+ * truncation-clipped off the right edge regardless of terminal width. */
+export const MAX_DESCRIPTOR_CHARS = 40;

package/extensions/subagent-widget/index.test.ts

@@ -213,12 +213,13 @@ describe("subagent-widget extension factory", () => {
 		expect(listRuns()).toHaveLength(0);
 	});
 
-	it("input evicts lingering finished runs on the next user turn", async () => {
+	it("input + turn_start both advance linger ages; evicts after COMPLETED_LINGER_TURNS boundaries", async () => {
 		const pi = makePi();
 		await initExtension(pi);
 		const startHandler = pi.handlers.get("tool_execution_start")!;
 		const endHandler = pi.handlers.get("tool_execution_end")!;
 		const inputHandler = pi.handlers.get("input")!;
+		const turnStartHandler = pi.handlers.get("turn_start")!;
 		await startHandler(
 			{
 				type: "tool_execution_start",
@@ -239,7 +240,52 @@ describe("subagent-widget extension factory", () => {
 			makeCtx(true),
 		);
 		expect(listRuns()).toHaveLength(1);
-		await inputHandler({ type: "input", text: "next", source: "interactive" } as any, makeCtx(true));
+		// COMPLETED_LINGER_TURNS = 3 — takes 3 turn boundaries to evict.
+		await turnStartHandler({ type: "turn_start" } as any, makeCtx(true)); // age 1
+		await turnStartHandler({ type: "turn_start" } as any, makeCtx(true)); // age 2
+		expect(listRuns()).toHaveLength(1);
+		await inputHandler({ type: "input", text: "next", source: "interactive" } as any, makeCtx(true)); // age 3 → evicted
 		expect(listRuns()).toHaveLength(0);
 	});
+
+	it("purges finished runs when a new wave starts (tool_execution_start with no active runs)", async () => {
+		const pi = makePi();
+		await initExtension(pi);
+		const startHandler = pi.handlers.get("tool_execution_start")!;
+		const endHandler = pi.handlers.get("tool_execution_end")!;
+		// Wave 1: dispatch + complete.
+		await startHandler(
+			{
+				type: "tool_execution_start",
+				toolCallId: "t1",
+				toolName: "subagent",
+				args: { agent: "scout", task: "x" },
+			},
+			makeCtx(true),
+		);
+		await endHandler(
+			{
+				type: "tool_execution_end",
+				toolCallId: "t1",
+				toolName: "subagent",
+				result: { details: { mode: "single", agentScope: "user", projectAgentsDir: null, results: [] } },
+				isError: false,
+			},
+			makeCtx(true),
+		);
+		expect(listRuns()).toHaveLength(1);
+		// Wave 2: new dispatch while wave 1 is still lingering → wave 1 purged first.
+		await startHandler(
+			{
+				type: "tool_execution_start",
+				toolCallId: "t2",
+				toolName: "subagent",
+				args: { agent: "worker", task: "y" },
+			},
+			makeCtx(true),
+		);
+		const runs = listRuns();
+		expect(runs).toHaveLength(1);
+		expect(runs[0].toolCallId).toBe("t2");
+	});
 });

package/extensions/subagent-widget/index.ts

@@ -49,15 +49,20 @@ export default async function (pi: ExtensionAPI) {
 		tracker.__resetState();
 	});
 
-	// User-turn boundary: advance linger ages on user input, NOT on "turn_start".
-	// Pi fires turn_start per agent-loop iteration (after each tool result,
-	// before the next assistant call), which would evict completed runs
-	// before the user sees them. "input" fires only on user-originated
-	// messages — the correct semantics for "persists until next user turn".
-	pi.on("input", async () => {
+	// Turn-boundary eviction: advance linger ages on BOTH user input and
+	// orchestrator agent-loop iterations. `input` fires on user-originated
+	// messages; `turn_start` fires per agent-loop iteration (after each tool
+	// result, before the next assistant call). Together with the bumped
+	// `COMPLETED_LINGER_TURNS=3` budget in constants.ts, completed rows stay
+	// visible long enough for the user to see, then auto-evict across
+	// ~3 orchestrator turns — no more "overlay sticks around forever" when
+	// the user doesn't immediately type back.
+	const advanceTurn = () => {
 		const evicted = tracker.onTurnStart();
 		if (evicted) widget?.update();
-	});
+	};
+	pi.on("input", async () => advanceTurn());
+	pi.on("turn_start", async () => advanceTurn());
 
 	// Background dispatches (args.async === true per pi-subagents@0.17.5 schema)
 	// return a job handle in ~100ms. Tracking them produces a misleading
@@ -70,6 +75,13 @@ export default async function (pi: ExtensionAPI) {
 	pi.on("tool_execution_start", async (event, ctx) => {
 		if (event.toolName !== SUBAGENT_TOOL) return;
 		if (isAsyncDispatch(event.args)) return;
+		// Wave-boundary purge: if no runs are currently active and we still
+		// have finished rows lingering from a prior wave, drop them before
+		// the new run appears. Prevents "new wave appends under yesterday's
+		// ✓ lines" when waves dispatch back-to-back without a user turn.
+		if (tracker.runningCount() === 0 && tracker.hasAnyVisible()) {
+			tracker.purgeFinished();
+		}
 		tracker.onStart(event.toolCallId, event.args);
 		if (ctx.hasUI) {
 			widget ??= new SubagentWidget();

package/extensions/subagent-widget/renderer-override.test.ts

@@ -1,5 +1,5 @@
 import type { Theme } from "@mariozechner/pi-coding-agent";
-import { Text } from "@mariozechner/pi-tui";
+import { Container, Text } from "@mariozechner/pi-tui";
 import { describe, expect, it, vi } from "vitest";
 
 // Stub the full renderer so the terminal-state branch returns a recognisable sentinel
@@ -11,7 +11,7 @@ const { renderSubagentResultMock } = vi.hoisted(() => ({
 }));
 vi.mock("pi-subagents/render", () => ({ renderSubagentResult: renderSubagentResultMock }));
 
-import { buildQuietRenderResult } from "./renderer-override.js";
+import { buildQuietRenderCall, buildQuietRenderResult } from "./renderer-override.js";
 
 function makeTheme(): Theme {
 	return {
@@ -20,63 +20,115 @@ function makeTheme(): Theme {
 	} as unknown as Theme;
 }
 
-describe("buildQuietRenderResult — layout-stable quiet card", () => {
-	it("emits ONE Text line when progress.status === 'running'", () => {
-		const render = buildQuietRenderResult();
-		const out = render(
-			{ details: { results: [{ agent: "x", progress: { status: "running" } }] } },
-			{ expanded: false },
-			makeTheme(),
-		);
+describe("buildQuietRenderCall — layout-stable status trailer from first frame", () => {
+	it("composes original call + status trailer when no original is provided", () => {
+		const render = buildQuietRenderCall(undefined);
+		// No original renderCall → just the trailer.
+		const out = render({}, makeTheme(), { executionStarted: false, state: {} });
 		expect(out).toBeInstanceOf(Text);
-		expect(renderSubagentResultMock).not.toHaveBeenCalled();
 	});
 
-	it("emits ONE Text line when progress.status === 'pending'", () => {
+	it("emits pending glyph when !executionStarted (before markExecutionStarted)", () => {
+		const render = buildQuietRenderCall(undefined);
+		const out = render({}, makeTheme(), { executionStarted: false, state: {} }) as Text;
+		// Our stubbed theme.fg is identity, so Text content includes the literal glyph + label.
+		const text = (out as unknown as { text?: string }).text ?? "";
+		expect(text).toContain("○");
+		expect(text).toContain("pending");
+	});
+
+	it("emits running glyph when executionStarted === true", () => {
+		const render = buildQuietRenderCall(undefined);
+		const out = render({}, makeTheme(), { executionStarted: true, state: {} }) as Text;
+		const text = (out as unknown as { text?: string }).text ?? "";
+		expect(text).toContain("◐");
+		expect(text).toContain("running");
+	});
+
+	it("wraps original call + trailer in a Container when both are present", () => {
+		const originalCall = vi.fn(() => new Text("subagent peer-comparator", 0, 0));
+		const render = buildQuietRenderCall(originalCall);
+		const out = render({}, makeTheme(), { executionStarted: true, state: {} });
+		expect(out).toBeInstanceOf(Container);
+		expect(originalCall).toHaveBeenCalledOnce();
+	});
+
+	it("suppresses trailer once state.subagentTerminal is set (final frame)", () => {
+		const originalCall = vi.fn(() => new Text("subagent peer-comparator", 0, 0));
+		const render = buildQuietRenderCall(originalCall);
+		const out = render({}, makeTheme(), { executionStarted: true, state: { subagentTerminal: true } });
+		// Should return the original call as-is, no Container wrapping with trailer.
+		expect(out).toBeInstanceOf(Text);
+		expect(originalCall).toHaveBeenCalledOnce();
+	});
+});
+
+describe("buildQuietRenderResult — non-terminal stub + terminal delegation", () => {
+	it("returns zero-height stub while progress.status === 'running' (renderCall owns trailer)", () => {
+		renderSubagentResultMock.mockClear();
 		const render = buildQuietRenderResult();
 		const out = render(
-			{ details: { results: [{ agent: "x", progress: { status: "pending" } }] } },
-			{ expanded: false },
+			{ details: { results: [{ agent: "x", progress: { status: "running" } }] } },
+			{ expanded: false, isPartial: true },
 			makeTheme(),
+			{ state: {} },
 		);
 		expect(out).toBeInstanceOf(Text);
+		expect(renderSubagentResultMock).not.toHaveBeenCalled();
 	});
 
-	it("emits ONE Text line when progress is MISSING (pre-progress partial update)", () => {
+	it("returns zero-height stub when progress is MISSING (pre-progress first frame)", () => {
+		renderSubagentResultMock.mockClear();
 		const render = buildQuietRenderResult();
-		// First partialResult often arrives before pi-subagents stamps progress.
-		// Previously fell through to full renderer → N-line card mid-stream →
-		// layout shift → physical-row stacking. Now stays 1-line.
-		const out = render({ details: { results: [{ agent: "x" }] } }, { expanded: false }, makeTheme());
+		const out = render({ details: { results: [{ agent: "x" }] } }, { expanded: false }, makeTheme(), { state: {} });
 		expect(out).toBeInstanceOf(Text);
 		expect(renderSubagentResultMock).not.toHaveBeenCalled();
 	});
 
-	it("emits ONE Text line when result.details itself is missing (very first frame)", () => {
+	it("returns zero-height stub when result.details is missing entirely", () => {
+		renderSubagentResultMock.mockClear();
 		const render = buildQuietRenderResult();
-		const out = render({}, { expanded: false }, makeTheme());
+		const out = render({}, { expanded: false }, makeTheme(), { state: {} });
 		expect(out).toBeInstanceOf(Text);
 	});
 
-	it("delegates to full renderer once exitCode lands (terminal state)", () => {
+	it("delegates to full renderer once terminal AND isPartial === false", () => {
 		renderSubagentResultMock.mockClear();
+		const state: { subagentTerminal?: boolean } = {};
 		const render = buildQuietRenderResult();
 		const out = render(
 			{ details: { results: [{ agent: "x", exitCode: 0, progress: { status: "complete" } }] } },
-			{ expanded: false },
+			{ expanded: false, isPartial: false },
 			makeTheme(),
+			{ state },
 		);
 		expect(renderSubagentResultMock).toHaveBeenCalledOnce();
 		expect((out as { __sentinel?: string }).__sentinel).toBe("full-render");
+		// State flag is set so renderCall suppresses its trailer next frame.
+		expect(state.subagentTerminal).toBe(true);
+	});
+
+	it("keeps stub when terminal but isPartial === true (don't commit until final)", () => {
+		renderSubagentResultMock.mockClear();
+		const render = buildQuietRenderResult();
+		const out = render(
+			{ details: { results: [{ agent: "x", exitCode: 0 }] } },
+			{ expanded: false, isPartial: true },
+			makeTheme(),
+			{ state: {} },
+		);
+		expect(out).toBeInstanceOf(Text);
+		expect(renderSubagentResultMock).not.toHaveBeenCalled();
 	});
 
-	it("delegates to full renderer on error stopReason", () => {
+	it("delegates to full renderer on error stopReason (terminal)", () => {
 		renderSubagentResultMock.mockClear();
 		const render = buildQuietRenderResult();
 		const out = render(
 			{ details: { results: [{ agent: "x", stopReason: "error" }] } },
-			{ expanded: false },
+			{ expanded: false, isPartial: false },
 			makeTheme(),
+			{ state: {} },
 		);
 		expect(renderSubagentResultMock).toHaveBeenCalledOnce();
 		expect((out as { __sentinel?: string }).__sentinel).toBe("full-render");
@@ -85,12 +137,11 @@ describe("buildQuietRenderResult — layout-stable quiet card", () => {
 	it("treats exitCode present + status=running as NON-terminal (streaming finalisation window)", () => {
 		renderSubagentResultMock.mockClear();
 		const render = buildQuietRenderResult();
-		// Mid-transition frames can have exitCode set before progress.status
-		// leaves "running". Should stay quiet until status clears.
 		const out = render(
 			{ details: { results: [{ agent: "x", exitCode: 0, progress: { status: "running" } }] } },
-			{ expanded: false },
+			{ expanded: false, isPartial: true },
 			makeTheme(),
+			{ state: {} },
 		);
 		expect(out).toBeInstanceOf(Text);
 		expect(renderSubagentResultMock).not.toHaveBeenCalled();

package/extensions/subagent-widget/renderer-override.ts

@@ -1,18 +1,28 @@
 /**
- * Quiet renderResult override for the nicobailon subagent tool.
+ * Quiet renderCall + renderResult overrides for the nicobailon subagent tool.
  *
  * Motivation: pi-coding-agent re-invokes `tool.renderResult` on every
  * `tool_execution_update` while a subagent is streaming. Nicobailon's
- * default renderer produces a multi-line Container (current tool,
- * recent output, recent tools, token line) that re-flows the inline
- * tool-call card on every frame → visible flicker. Our `aboveEditor`
- * overlay (widget.ts) is the authoritative live view; the inline card
- * should be static while running, full at completion.
+ * default renderer produces a multi-line Container that re-flows the
+ * inline tool-call card on every frame → visible flicker and row
+ * stacking. Our `aboveEditor` overlay (widget.ts) is the authoritative
+ * live view; the inline card should be layout-stable while running,
+ * then unfold to full result at completion.
+ *
+ * Layout-stability contract (see issue doc in CHANGELOG 0.12.3):
+ *   - `renderCall` always appends a 1-line `◐ pending` / `◐ running`
+ *     trailer below pi-subagents' own call header. So the card is 2
+ *     lines from the very first paint — no more 1↔2-line oscillation.
+ *   - `renderResult` emits a zero-height stub while non-terminal (the
+ *     status line is owned by renderCall), then delegates to
+ *     `renderSubagentResult` once the last SingleResult carries a
+ *     terminal exitCode/stopReason. A shared `ctx.state.subagentTerminal`
+ *     flag tells renderCall to stop emitting its trailer so we don't
+ *     duplicate status text next to the full result block.
  *
  * Mechanism: wrap the ExtensionAPI handed to nicobailon's default
  * export in a Proxy that intercepts `registerTool` for the "subagent"
- * tool and swaps its `renderResult` with ours. All other tools +
- * every other ExtensionAPI method pass through unchanged.
+ * tool and swaps both `renderCall` and `renderResult`.
  *
  * Deployment: settings.json must not list `"npm:pi-subagents"` — only
  * this wrapper loads nicobailon (via `registerSubagentExtension(pi)`)
@@ -22,7 +32,7 @@
  */
 
 import type { ExtensionAPI, Theme } from "@mariozechner/pi-coding-agent";
-import { Text } from "@mariozechner/pi-tui";
+import { type Component, Container, Text } from "@mariozechner/pi-tui";
 import registerSubagentExtension from "pi-subagents";
 import { renderSubagentResult } from "pi-subagents/render";
 
@@ -41,16 +51,9 @@ interface DetailsLike {
 	results?: ResultLike[];
 }
 
-// Layout-stable quiet card height: while the subagent is non-terminal, emit EXACTLY
-// one `Text` line. If we fell through to the full renderer whenever progress.status
-// was missing (pre-progress partial updates), the card would flip 1-line ↔ N-line
-// every few frames mid-stream — same physical-row-stacking pathology that ghosted
-// the overlay rows before the run-tracker newline fix.
-//
-// Terminal state: exitCode or stopReason is present on the last SingleResult AND
-// progress.status is not in the running set. Anything else is treated as running,
-// including "no progress yet" (status === undefined) and the first tool_execution_*
-// frames before pi-subagents has stamped progress.
+// Terminal = last SingleResult carries a definite exitCode or stopReason AND
+// progress.status is not explicitly running/pending. Anything else counts as
+// non-terminal, including "no progress yet" (pre-progress partial updates).
 function isTerminal(r: ResultLike | undefined): boolean {
 	if (!r) return false;
 	const status = r.progress?.status;
@@ -58,39 +61,91 @@ function isTerminal(r: ResultLike | undefined): boolean {
 	return r.exitCode != null || r.stopReason != null;
 }
 
+// Shared per-component state written by renderResult (terminal frame) and
+// read by renderCall (to suppress the status trailer once the full block renders).
+interface SharedState {
+	subagentTerminal?: boolean;
+}
+
+// Render context shape used by Pi's ToolExecutionComponent
+// (see @mariozechner/pi-coding-agent/dist/modes/interactive/components/tool-execution.js:85).
+// We only read the fields we need — the rest of the context is opaque.
+interface RenderCallCtx {
+	executionStarted?: boolean;
+	state?: SharedState;
+}
+
+interface RenderResultCtx {
+	state?: SharedState;
+}
+
+function buildStatusTrailer(theme: Theme, ctx: RenderCallCtx): Text {
+	// `executionStarted` flips true once Pi fires markExecutionStarted(), i.e.
+	// the tool is actually running (not just queued with complete args).
+	const running = ctx.executionStarted === true;
+	const glyph = running ? theme.fg("warning", "◐") : theme.fg("dim", "○");
+	const label = running ? "running" : "pending";
+	return new Text(`${glyph} ${theme.fg("muted", label)}`, 0, 0);
+}
+
+// Type for pi-subagents' original renderCall; we pass through to it for the
+// call header and append our status trailer below in a Container.
+type OriginalRenderCall = (args: unknown, theme: Theme, ctx: unknown) => Component | undefined;
+
+export function buildQuietRenderCall(originalRenderCall: OriginalRenderCall | undefined): OriginalRenderCall {
+	return (args, theme, ctx) => {
+		const callCtx = (ctx ?? {}) as RenderCallCtx;
+		const original = originalRenderCall ? originalRenderCall(args, theme, ctx) : undefined;
+		// Terminal frame: renderResult owns the full display below the call header;
+		// no trailer here, otherwise we'd duplicate status.
+		if (callCtx.state?.subagentTerminal === true) {
+			return original ?? new Text("", 0, 0);
+		}
+		const trailer = buildStatusTrailer(theme, callCtx);
+		if (!original) return trailer;
+		const container = new Container();
+		container.addChild(original);
+		container.addChild(trailer);
+		return container;
+	};
+}
+
 export function buildQuietRenderResult(): (
 	result: { details?: DetailsLike; content?: Array<{ type: string; text?: string }> },
-	options: { expanded: boolean },
+	options: { expanded: boolean; isPartial?: boolean },
 	theme: Theme,
+	ctx?: unknown,
 ) => unknown {
-	return (result, options, theme) => {
+	return (result, options, theme, ctx) => {
 		const r = result.details?.results?.[0];
-		if (isTerminal(r)) {
+		const resultCtx = (ctx ?? {}) as RenderResultCtx;
+		if (isTerminal(r) && options.isPartial !== true) {
+			// Mark state so the NEXT renderCall invocation suppresses its trailer —
+			// prevents "◐ running" appearing above the final result block.
+			if (resultCtx.state) resultCtx.state.subagentTerminal = true;
 			return renderSubagentResult(result, options, theme);
 		}
-		// Non-terminal → single-line status. Renders under the tool-call header,
-		// glyph at column 0 to align with "subagent <agent>" above. Glyphs mirror
-		// packages/rpiv-todo/todo-overlay.ts:28-35 for consistent status language.
-		const status = r?.progress?.status ?? "running";
-		const glyph = status === "pending" ? theme.fg("dim", "○") : theme.fg("warning", "◐");
-		return new Text(`${glyph} ${theme.fg("muted", status)}`, 0, 0);
+		// Non-terminal: status line is owned by renderCall. Return a zero-height
+		// stub so the card's total height = exactly (call header + 1 trailer).
+		return new Text("", 0, 0);
 	};
 }
 
 /**
  * Invoke nicobailon's registerSubagentExtension with a proxied pi that
- * overrides the "subagent" tool's renderResult on its way into the
- * extension runtime. Idempotent iff called once per session.
+ * overrides the "subagent" tool's renderCall + renderResult on the way
+ * into the extension runtime. Idempotent iff called once per session.
  */
 export async function registerSubagentsWithQuietRenderer(pi: ExtensionAPI): Promise<void> {
 	const quietRenderResult = buildQuietRenderResult();
 	const wrappedPi = new Proxy(pi, {
 		get(target, prop, receiver) {
 			if (prop !== "registerTool") return Reflect.get(target, prop, receiver);
-			return (tool: { name: string; renderResult?: unknown }) => {
+			return (tool: { name: string; renderCall?: unknown; renderResult?: unknown }) => {
 				if (tool.name === SUBAGENT_TOOL) {
 					return (target.registerTool as unknown as (t: unknown) => void)({
 						...tool,
+						renderCall: buildQuietRenderCall(tool.renderCall as OriginalRenderCall | undefined),
 						renderResult: quietRenderResult,
 					});
 				}

package/extensions/subagent-widget/run-tracker.test.ts

@@ -148,21 +148,28 @@ describe("run-tracker onEnd", () => {
 });
 
 describe("run-tracker onTurnStart (turn-based linger)", () => {
-	it("evicts completed runs on the first turn boundary", () => {
+	// COMPLETED_LINGER_TURNS = 3 → evict on the 3rd turn boundary.
+	it("evicts completed runs after COMPLETED_LINGER_TURNS boundaries", () => {
 		onStart("t1", { agent: "scout", task: "x" });
 		onEnd("t1", { details: makeDetails("single", [makeResult()]) }, false);
 		expect(listRuns()).toHaveLength(1);
-		const evicted = onTurnStart();
-		expect(evicted).toBe(true);
+		expect(onTurnStart()).toBe(false); // age 1
+		expect(onTurnStart()).toBe(false); // age 2
+		expect(listRuns()).toHaveLength(1);
+		expect(onTurnStart()).toBe(true); // age 3 → evicted
 		expect(listRuns()).toHaveLength(0);
 	});
 
-	it("keeps error runs through two turn boundaries", () => {
+	// ERROR_LINGER_TURNS = 5 → evict on the 5th turn boundary.
+	it("keeps error runs through ERROR_LINGER_TURNS boundaries", () => {
 		onStart("t1", { agent: "scout", task: "x" });
 		onEnd("t1", { details: makeDetails("single", [makeResult({ exitCode: 1 })]) }, true);
-		expect(onTurnStart()).toBe(false);
+		expect(onTurnStart()).toBe(false); // age 1
+		expect(onTurnStart()).toBe(false); // age 2
+		expect(onTurnStart()).toBe(false); // age 3
+		expect(onTurnStart()).toBe(false); // age 4
 		expect(listRuns()).toHaveLength(1);
-		expect(onTurnStart()).toBe(true);
+		expect(onTurnStart()).toBe(true); // age 5 → evicted
 		expect(listRuns()).toHaveLength(0);
 	});
 

package/extensions/subagent-widget/run-tracker.ts

@@ -144,6 +144,22 @@ export function onTurnStart(): boolean {
 	return evicted;
 }
 
+/** Evict all finished (non-running) runs immediately. Used at wave boundaries
+ * so a fresh subagent dispatch starts with a clean overlay instead of new rows
+ * appended under lingering ✓ lines from the prior wave. Returns true iff at
+ * least one run was evicted. */
+export function purgeFinished(): boolean {
+	let evicted = false;
+	for (const [id, run] of runs) {
+		if (run.status !== "running") {
+			runs.delete(id);
+			finishedAge.delete(id);
+			evicted = true;
+		}
+	}
+	return evicted;
+}
+
 /** Snapshot of currently-visible runs. Callers must not retain references. */
 export function listRuns(): readonly TrackedRun[] {
 	return [...runs.values()];

package/extensions/subagent-widget/widget.render.test.ts

@@ -78,15 +78,16 @@ describe("SubagentWidget render — empty", () => {
 });
 
 describe("SubagentWidget render — single", () => {
-	it("renders heading + 2-line running block", () => {
+	it("renders heading + 2-line running block + trailing blank separator", () => {
 		onStart("t1", { agent: "scout", task: "probe" });
 		onUpdate("t1", makeDetails("single", [makeResult()]));
 		const { ctx, captured } = makeUICtx();
 		const lines = renderOnce(new SubagentWidget(), ctx, captured);
-		expect(lines).toHaveLength(3);
+		expect(lines).toHaveLength(4);
 		expect(lines[0]).toContain("Subagents");
 		expect(lines[1]).toContain("scout");
 		expect(lines[2]).toContain("⎿");
+		expect(lines[3]).toBe("");
 	});
 
 	it("renders live tool-uses + tokens from details.progress during streaming", () => {
@@ -188,21 +189,45 @@ describe("SubagentWidget render — overflow", () => {
 		}
 		const { ctx, captured } = makeUICtx();
 		const lines = renderOnce(new SubagentWidget(), ctx, captured);
-		expect(lines.length).toBeLessThanOrEqual(12);
-		const footer = lines[lines.length - 1];
+		// MAX_WIDGET_LINES (12) + 1 trailing blank separator.
+		expect(lines.length).toBeLessThanOrEqual(13);
+		// Last real line is the footer; appended blank separator sits below.
+		expect(lines[lines.length - 1]).toBe("");
+		const footer = lines[lines.length - 2];
 		expect(footer).toMatch(/\+\d+ more/);
 		expect(footer).toContain("running");
 	});
 });
 
 describe("SubagentWidget render — tail connector", () => {
-	it("swaps ├─ to └─ on the final line when nothing else follows", () => {
+	it("swaps ├─ to └─ on the final tree line when nothing else follows (trailing blank ignored)", () => {
 		onStart("t1", { agent: "scout", task: "probe" });
 		onEnd("t1", { details: makeDetails("single", [makeResult()]) }, false);
 		const { ctx, captured } = makeUICtx();
 		const lines = renderOnce(new SubagentWidget(), ctx, captured);
-		expect(lines[lines.length - 1]).toContain("└─");
-		expect(lines[lines.length - 1]).not.toMatch(/^├─/);
+		// Last entry is the trailing blank separator; the tree line is the one above.
+		expect(lines[lines.length - 1]).toBe("");
+		expect(lines[lines.length - 2]).toContain("└─");
+		expect(lines[lines.length - 2]).not.toMatch(/^├─/);
+	});
+});
+
+describe("SubagentWidget render — separator", () => {
+	it("appends an empty trailing line so adjacent widgets don't hug the tree", () => {
+		onStart("t1", { agent: "scout", task: "probe" });
+		onUpdate("t1", makeDetails("single", [makeResult()]));
+		const { ctx, captured } = makeUICtx();
+		const lines = renderOnce(new SubagentWidget(), ctx, captured);
+		expect(lines[lines.length - 1]).toBe("");
+	});
+
+	it("returns [] (no trailing blank) when there are no tracked runs", () => {
+		const { ctx, captured } = makeUICtx();
+		const widget = new SubagentWidget();
+		widget.setUICtx(ctx);
+		widget.update();
+		const comp = captured[0].factory?.(makeTUI(), makeTheme());
+		expect(comp?.render(120)).toEqual([]);
 	});
 });
 
@@ -266,3 +291,41 @@ describe("SubagentWidget render — newline safety", () => {
 		}
 	});
 });
+
+describe("SubagentWidget render — descriptor character cap", () => {
+	it("truncates long task descriptions with ellipsis (running row)", () => {
+		onStart("t1", {
+			agent: "peer-comparator",
+			task: "Peer-mirror check. PeerPairs (orchestrator-computed): 1. (TruVisibility.TruEcommerce.Domain/Subscriptions/PhysicalProductSubscriptionProcessService.cs)",
+		});
+		onUpdate("t1", makeDetails("single", [makeResult()]));
+		const { ctx, captured } = makeUICtx();
+		const lines = renderOnce(new SubagentWidget(), ctx, captured);
+		// Stats tail ("⟳…tool uses…tokens…running") must still be visible.
+		expect(lines[1]).toMatch(/running/);
+		// Capped line includes the ellipsis marker.
+		expect(lines[1]).toContain("…");
+	});
+
+	it("truncates long task descriptions with ellipsis (finished row)", () => {
+		onStart("t1", {
+			agent: "peer-comparator",
+			task: "Peer-mirror check. PeerPairs (orchestrator-computed): 1. (TruVisibility.TruEcommerce.Domain/Subscriptions/PhysicalProductSubscriptionProcessService.cs)",
+		});
+		onEnd("t1", { details: makeDetails("single", [makeResult()]) }, false);
+		const { ctx, captured } = makeUICtx();
+		const lines = renderOnce(new SubagentWidget(), ctx, captured);
+		// Finished line includes stats (1 tool use / tokens / duration) — no `running`.
+		expect(lines[1]).not.toMatch(/running/);
+		expect(lines[1]).toContain("…");
+	});
+
+	it("preserves short task descriptions without ellipsis", () => {
+		onStart("t1", { agent: "scout", task: "probe auth module" });
+		onUpdate("t1", makeDetails("single", [makeResult()]));
+		const { ctx, captured } = makeUICtx();
+		const lines = renderOnce(new SubagentWidget(), ctx, captured);
+		expect(lines[1]).toContain("probe auth module");
+		expect(lines[1]).not.toContain("…");
+	});
+});

package/extensions/subagent-widget/widget.ts

@@ -14,17 +14,20 @@
 import type { ExtensionUIContext, Theme } from "@mariozechner/pi-coding-agent";
 import { type TUI, truncateToWidth } from "@mariozechner/pi-tui";
 import { describeActivity, formatDuration, formatTokens, formatToolUses, formatTurns } from "./activity.js";
-import { MAX_WIDGET_LINES, SPINNER, TICK_MS, WIDGET_KEY } from "./constants.js";
+import { MAX_DESCRIPTOR_CHARS, MAX_WIDGET_LINES, SPINNER, TICK_MS, WIDGET_KEY } from "./constants.js";
 import { listRuns, runningCount } from "./run-tracker.js";
 import type { AgentProgress, SingleResult, TrackedRun } from "./types.js";
 
-// Strip SGR ANSI escapes to measure visible width for layout math.
-const ANSI_RE = /\x1b\[[0-9;]*m/g;
-const visibleLen = (s: string): number => s.replace(ANSI_RE, "").length;
 // Defensive: any \n in a returned string[] element splits into physical rows pi-tui can't
 // track, leaving stale artifacts every frame. Run-tracker sanitizes at ingest; this guard
 // covers any future caller that mutates description/displayName directly on the tracked run.
 const oneLine = (s: string): string => s.replace(/\s*[\r\n]+\s*/g, " ");
+// Character cap on the descriptor column. Keeps stats visible on both running
+// and finished rows regardless of terminal width — prior width-aware budget
+// let long prompts push stats off the right edge where `truncateToWidth`
+// silently clipped them with "...".
+const capDescriptor = (s: string): string =>
+	s.length <= MAX_DESCRIPTOR_CHARS ? s : `${s.slice(0, MAX_DESCRIPTOR_CHARS - 1)}…`;
 
 export class SubagentWidget {
 	private uiCtx: ExtensionUIContext | undefined;
@@ -98,7 +101,10 @@ export class SubagentWidget {
 		const runs = listRuns();
 		if (runs.length === 0) return [];
 
-		const truncate = (line: string) => truncateToWidth(line, width);
+		// Single-char `…` marker matches our descriptor cap (capDescriptor) and the
+		// activity-line helper (activity.ts:truncateLine). pi-tui's default is "..."
+		// which would mix two ellipsis styles inside the same widget.
+		const truncate = (line: string) => truncateToWidth(line, width, "…");
 		const frame = SPINNER[this.widgetFrame % SPINNER.length];
 		const active = runningCount() > 0;
 
@@ -110,7 +116,7 @@ export class SubagentWidget {
 		const finishedLines: string[] = [];
 		for (const run of runs) {
 			if (run.status === "running") {
-				runningBlocks.push(this.renderRunningBlock(run, theme, frame, truncate, width));
+				runningBlocks.push(this.renderRunningBlock(run, theme, frame, truncate));
 			} else {
 				finishedLines.push(this.renderFinishedLine(run, theme, truncate));
 			}
@@ -124,6 +130,10 @@ export class SubagentWidget {
 			for (const pair of runningBlocks) lines.push(...pair);
 			lines.push(...finishedLines);
 			this.fixupLastConnector(lines, runningBlocks.length, finishedLines.length);
+			// Trailing blank separates our overlay from whatever sits below (Todos,
+			// editor, next widget). Without it our last tree row hugs the next
+			// overlay's heading row with no visual break.
+			lines.push("");
 			return lines;
 		}
 
@@ -153,6 +163,7 @@ export class SubagentWidget {
 		if (hiddenFinished > 0) parts.push(`${hiddenFinished} finished`);
 		const footer = parts.length > 0 ? `+${total} more (${parts.join(", ")})` : `+${total} more`;
 		lines.push(truncate(`${theme.fg("dim", "└─")} ${theme.fg("dim", footer)}`));
+		lines.push("");
 		return lines;
 	}
 
@@ -166,17 +177,10 @@ export class SubagentWidget {
 		}
 	}
 
-	private renderRunningBlock(
-		run: TrackedRun,
-		theme: Theme,
-		frame: string,
-		truncate: (s: string) => string,
-		width: number,
-	): string[] {
+	private renderRunningBlock(run: TrackedRun, theme: Theme, frame: string, truncate: (s: string) => string): string[] {
 		// Layout: `├─ {frame} {bold(name)}  {muted(descriptor)} · {dim(stats)}`.
-		// Mirrors tintinweb/pi-subagents agent-widget.ts but with width-aware
-		// descriptor truncation so stats stay visible on narrow terminals
-		// (naive truncateToWidth would cut the rightmost stats tail first).
+		// Descriptor capped by `MAX_DESCRIPTOR_CHARS` so the stats tail is never
+		// clipped off the right edge by `truncateToWidth`.
 		const last = run.results[run.results.length - 1];
 		const progress = run.progress?.[run.progress.length - 1];
 		const stats = this.buildStats(run);
@@ -196,9 +200,7 @@ export class SubagentWidget {
 
 		const prefix = `${theme.fg("dim", "├─")} ${theme.fg("accent", frame)} ${theme.bold(oneLine(run.displayName))}`;
 		const tail = `${theme.fg("dim", "·")} ${theme.fg("dim", stats)}`;
-		// Overhead: "  " between prefix+descriptor, " " between descriptor+tail.
-		const budget = Math.max(0, width - visibleLen(prefix) - 2 - 1 - visibleLen(tail));
-		const descriptorOut = visibleLen(descriptor) > budget ? descriptor.slice(0, budget).trimEnd() : descriptor;
+		const descriptorOut = capDescriptor(descriptor);
 		const middle = descriptorOut ? `  ${theme.fg("muted", descriptorOut)} ` : "  ";
 		const activity = describeActivity(last, progress);
 		return [
@@ -229,7 +231,7 @@ export class SubagentWidget {
 			trail = theme.fg("error", ` error${msg}`);
 		}
 		const body =
-			`${icon} ${theme.fg("dim", oneLine(run.displayName))}  ${theme.fg("dim", oneLine(run.description))} ` +
+			`${icon} ${theme.fg("dim", oneLine(run.displayName))}  ${theme.fg("dim", capDescriptor(oneLine(run.description)))} ` +
 			`${theme.fg("dim", "·")} ${theme.fg("dim", stats)}${trail}`;
 		return truncate(`${theme.fg("dim", "├─")} ${body}`);
 	}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@juicesharp/rpiv-pi",
-  "version": "0.12.2",
+  "version": "0.12.3",
   "description": "Skill-based development workflow for Pi Agent — discover, research, design, plan, implement, validate",
   "keywords": [
     "pi-package",