@bastani/atomic 0.9.2 → 0.9.3-alpha.2

package/dist/builtin/subagents/src/extension/index.ts

@@ -10,7 +10,7 @@ import { discoverAgents } from "../agents/agents.ts";
 import { cleanupAllArtifactDirs, cleanupOldArtifacts, getArtifactsDir } from "../shared/artifacts.ts";
 import { resolveCurrentSessionId } from "../shared/session-identity.ts";
 import { cleanupOldChainDirs } from "../shared/settings.ts";
-import { renderLiveSubagentResult, renderSubagentResult, stopResultAnimations, stopWidgetAnimation, type SubagentResultRenderState } from "../tui/render.ts";
+import { advanceResultPulseFrame, renderLiveSubagentResult, renderSubagentResult, stopResultAnimations, stopWidgetAnimation, type SubagentResultRenderState } from "../tui/render.ts";
 import { SubagentParams } from "./schemas.ts";
 import { createSubagentExecutor, type SubagentParamsLike } from "../runs/foreground/subagent-executor.ts";
 import { createAsyncJobTracker } from "../runs/background/async-job-tracker.ts";
@@ -69,7 +69,7 @@ type SubagentToolRenderState = SubagentResultRenderState;
 function rebuildSlashResultContainer(
 	container: Container,
 	result: AgentToolResult<Details>,
-	options: { expanded: boolean; now?: number },
+	options: { expanded: boolean; now?: number; pulseFrame?: number },
 	theme: ExtensionContext["ui"]["theme"],
 ): void {
 	container.clear();
@@ -87,12 +87,14 @@ function createSlashResultComponent(
 	const container = new Container();
 	let lastVersion = -1;
 	let lastSnapshotNow = 0;
+	let pulseFrame = 0;
 	container.render = (width: number): string[] => {
 		const snapshot = getSlashRenderableSnapshot(details);
 		if (snapshot.version !== lastVersion) {
 			lastVersion = snapshot.version;
 			lastSnapshotNow = Date.now();
-			rebuildSlashResultContainer(container, snapshot.result, { ...options, now: lastSnapshotNow }, theme);
+			pulseFrame = advanceResultPulseFrame(pulseFrame);
+			rebuildSlashResultContainer(container, snapshot.result, { ...options, now: lastSnapshotNow, pulseFrame }, theme);
 		}
 		return Container.prototype.render.call(container, width);
 	};
@@ -179,6 +181,7 @@ export default function registerSubagentExtension(pi: ExtensionAPI): void {
 		baseCwd: "",
 		currentSessionId: null,
 		asyncJobs: new Map(),
+		subagentInProgress: false,
 		foregroundRuns: new Map(),
 		foregroundControls: new Map(),
 		lastForegroundControlId: null,

package/dist/builtin/subagents/src/extension/schemas.ts

@@ -3,7 +3,7 @@
  */
 
 import { Type } from "typebox";
-import { SUBAGENT_ACTIONS } from "../shared/types.ts";
+import { MAX_SUBAGENT_NESTING_DEPTH, SUBAGENT_ACTIONS } from "../shared/types.ts";
 
 const SkillOverride = Type.Unsafe({
 	anyOf: [
@@ -137,11 +137,6 @@ const ChainItem = Type.Object({
 }, {
 	description: "Chain step: use {agent, task?, ...} for sequential, {parallel: [...]} for static concurrent execution, or {expand, parallel: {...}, collect} for dynamic fanout.",
 	additionalProperties: false,
-	allOf: [
-		{ if: { required: ["expand"] }, then: { required: ["parallel", "collect"], properties: { parallel: { type: "object" } } } },
-		{ if: { required: ["collect"] }, then: { required: ["expand", "parallel"], properties: { parallel: { type: "object" } } } },
-		{ not: { required: ["expand"], properties: { parallel: { type: "array", items: {} } } } },
-	],
 });
 
 const ControlOverrides = Type.Object({
@@ -188,7 +183,7 @@ export const SubagentParams = Type.Object({
 			{ type: "object", additionalProperties: true },
 			{ type: "string" },
 		],
-		description: "Agent or chain config for create/update. Agent: name, package (optional namespace; runtime name becomes package.name), description, scope ('user'|'project', default 'user'), systemPrompt, systemPromptMode, inheritProjectContext, inheritSkills, defaultContext ('fresh'|'fork'), model, tools (comma-separated), extensions (comma-separated), skills (comma-separated), thinking, output, reads, progress, maxSubagentDepth. Chain: name, package, description, scope, steps (array of {agent, task?, output?, outputMode?, reads?, model?, skill?, progress?}). Presence of 'steps' creates a chain instead of an agent. String values must be valid JSON."
+		description: `Agent or chain config for create/update. Agent: name, package (optional namespace; runtime name becomes package.name), description, scope ('user'|'project', default 'user'), systemPrompt, systemPromptMode, inheritProjectContext, inheritSkills, defaultContext ('fresh'|'fork'), model, tools (comma-separated), extensions (comma-separated), skills (comma-separated), thinking, output, reads, progress, maxSubagentDepth (integer >= 0, clamped to ${MAX_SUBAGENT_NESTING_DEPTH}). Chain: name, package, description, scope, steps (array of {agent, task?, output?, outputMode?, reads?, model?, skill?, progress?}). Presence of 'steps' creates a chain instead of an agent. String values must be valid JSON.`
 	})),
 	tasks: Type.Optional(Type.Array(TaskItem, { description: "PARALLEL mode: [{agent, task, count?, output?, outputMode?, reads?, progress?}, ...]" })),
 	concurrency: Type.Optional(Type.Integer({ minimum: 1, description: "Top-level PARALLEL mode only: max concurrent tasks. Defaults to config.parallel.concurrency or 4." })),

package/dist/builtin/subagents/src/intercom/result-intercom.ts

@@ -10,6 +10,7 @@ import {
 	type SubagentResultIntercomPayload,
 	type SubagentResultStatus,
 	type SubagentRunMode,
+	MAX_SUBAGENT_NESTING_DEPTH,
 	SUBAGENT_RESULT_INTERCOM_DELIVERY_EVENT,
 	SUBAGENT_RESULT_INTERCOM_EVENT,
 } from "../shared/types.ts";
@@ -69,7 +70,7 @@ function compactNestedRun(run: NestedRunSummary | PublicNestedRunSummary, depth
 		...(run.parentStepIndex !== undefined ? { parentStepIndex: run.parentStepIndex } : {}),
 		...(run.parentAgent ? { parentAgent: run.parentAgent } : {}),
 		depth: run.depth,
-		path: run.path.slice(0, 4).map((part) => ({
+		path: run.path.slice(0, MAX_SUBAGENT_NESTING_DEPTH + 1).map((part) => ({
 			runId: part.runId,
 			...(part.stepIndex !== undefined ? { stepIndex: part.stepIndex } : {}),
 			...(part.agent ? { agent: part.agent } : {}),
@@ -114,9 +115,9 @@ function compactNestedRun(run: NestedRunSummary | PublicNestedRunSummary, depth
 			...(step.startedAt !== undefined ? { startedAt: step.startedAt } : {}),
 			...(step.endedAt !== undefined ? { endedAt: step.endedAt } : {}),
 			...(step.error ? { error: step.error } : {}),
-			...(depth < 2 && step.children?.length ? { children: step.children.slice(0, 8).map((child) => compactNestedRun(child, depth + 1)) } : {}),
+			...(depth < MAX_SUBAGENT_NESTING_DEPTH && step.children?.length ? { children: step.children.slice(0, 8).map((child) => compactNestedRun(child, depth + 1)) } : {}),
 		})) } : {}),
-		...(depth < 2 && run.children?.length ? { children: run.children.slice(0, 8).map((child) => compactNestedRun(child, depth + 1)) } : {}),
+		...(depth < MAX_SUBAGENT_NESTING_DEPTH && run.children?.length ? { children: run.children.slice(0, 8).map((child) => compactNestedRun(child, depth + 1)) } : {}),
 	};
 }
 

package/dist/builtin/subagents/src/runs/background/async-job-tracker.ts

@@ -395,10 +395,7 @@ export function createAsyncJobTracker(pi: Pick<ExtensionAPI, "events">, state: S
 		state.foregroundControls?.clear();
 		state.lastForegroundControlId = null;
 		state.resultFileCoalescer.clear();
-		if (ctx?.hasUI) {
-			state.lastUiContext = ctx;
-			rerenderWidget(ctx, []);
-		}
+		if (ctx?.hasUI) state.lastUiContext = ctx;
 	};
 
 	return { ensurePoller, handleStarted, handleComplete, resetJobs, hydrateActiveJobs };

package/dist/builtin/subagents/src/runs/foreground/subagent-executor-single.ts

@@ -25,11 +25,25 @@ import {
 	wrapForkTask,
 	type AgentProgress,
 	type ArtifactPaths,
+	type SingleResult,
 	type SubagentToolResult,
 } from "../../shared/types.ts";
 import type { ExecutionContextData, ResolvedExecutorDeps } from "./subagent-executor-types.ts";
 import { createForegroundControlNotifier, maybeBuildForegroundIntercomReceipt, rememberForegroundRun } from "./subagent-executor-status.ts";
 
+function formatFailedSingleRunOutput(result: SingleResult, displayOutput: string): string {
+	const error = result.error || "Failed";
+	const output = displayOutput.trim();
+	const lines = [error];
+	if (output && output !== error.trim()) {
+		lines.push("", "Output:", output);
+	}
+	if (result.artifactPaths?.outputPath) {
+		lines.push("", `Output artifact: ${result.artifactPaths.outputPath}`);
+	}
+	return lines.join("\n");
+}
+
 export async function runSinglePath(data: ExecutionContextData, deps: ResolvedExecutorDeps): Promise<SubagentToolResult> {
 	const {
 		params,
@@ -309,7 +323,7 @@ export async function runSinglePath(data: ExecutionContextData, deps: ResolvedEx
 
 	if (r.exitCode !== 0)
 		return {
-			content: [{ type: "text", text: r.error || "Failed" }],
+			content: [{ type: "text", text: formatFailedSingleRunOutput(r, finalizedOutput.displayOutput) }],
 			details,
 			isError: true,
 		};

package/dist/builtin/subagents/src/runs/foreground/subagent-executor.ts

@@ -172,6 +172,23 @@ async function handleInterruptRequest(input: {
 	};
 }
 
+function inferExecutionMode(params: SubagentParamsLike): "single" | "parallel" | "chain" {
+	if ((params.chain?.length ?? 0) > 0) return "chain";
+	if ((params.tasks?.length ?? 0) > 0) return "parallel";
+	return "single";
+}
+
+function duplicateSubagentCallResult(params: SubagentParamsLike): SubagentToolResult {
+	return {
+		content: [{
+			type: "text",
+			text: "Rejected: a subagent call is already in progress. Issue exactly ONE subagent call per turn.",
+		}],
+		isError: true,
+		details: { mode: inferExecutionMode(params), results: [] },
+	};
+}
+
 export function createSubagentExecutor(rawDeps: ExecutorDeps): {
 	execute: (
 		id: string,
@@ -249,5 +266,22 @@ export function createSubagentExecutor(rawDeps: ExecutorDeps): {
 		}, prepared.effectiveParams.context);
 	};
 
-	return { execute };
+	const executeWithSingleDispatchGuard = async (
+		id: string,
+		params: SubagentParamsLike,
+		signal: AbortSignal,
+		onUpdate: ((r: SubagentToolResult) => void) | undefined,
+		ctx: ExtensionContext,
+	): Promise<SubagentToolResult> => {
+		if (params.action) return execute(id, params, signal, onUpdate, ctx);
+		if (deps.state.subagentInProgress === true) return duplicateSubagentCallResult(params);
+		deps.state.subagentInProgress = true;
+		try {
+			return await execute(id, params, signal, onUpdate, ctx);
+		} finally {
+			deps.state.subagentInProgress = false;
+		}
+	};
+
+	return { execute: executeWithSingleDispatchGuard };
 }

package/dist/builtin/subagents/src/runs/shared/mcp-direct-tool-allowlist.ts

@@ -7,7 +7,7 @@ import { getAgentDir } from "../../shared/utils.ts";
 
 const CACHE_VERSION = 1;
 const CACHE_MAX_AGE_MS = 7 * 24 * 60 * 60 * 1000;
-const BUILTIN_TOOL_NAMES = new Set(["read", "bash", "edit", "write", "grep", "find", "ls", "mcp"]);
+const BUILTIN_TOOL_NAMES = new Set(["read", "bash", "edit", "write", "grep", "find", "search", "ls", "mcp"]);
 const GENERIC_GLOBAL_CONFIG_PATH = path.join(os.homedir(), ".config", "mcp", "mcp.json");
 const IMPORT_PATHS = {
 	cursor: [path.join(os.homedir(), ".cursor", "mcp.json")],

package/dist/builtin/subagents/src/runs/shared/nested-render.ts

@@ -1,6 +1,6 @@
 import { formatDuration, formatTokens, shortenPath } from "../../shared/formatters.ts";
 import { formatActivityLabel } from "../../shared/status-format.ts";
-import type { ActivityState, NestedRunSummary } from "../../shared/types.ts";
+import { MAX_SUBAGENT_NESTING_DEPTH, type ActivityState, type NestedRunSummary } from "../../shared/types.ts";
 
 export interface NestedRunCounts {
 	total: number;
@@ -108,7 +108,7 @@ function formatNestedRunLines(children: NestedRunSummary[] | undefined, options:
 export function formatNestedRunStatusLines(children: NestedRunSummary[] | undefined, options: { indent?: string; maxDepth?: number; maxLines?: number; commandHints?: boolean } = {}): string[] {
 	return formatNestedRunLines(children, {
 		indent: options.indent ?? "  ",
-		maxDepth: options.maxDepth ?? 2,
+		maxDepth: options.maxDepth ?? MAX_SUBAGENT_NESTING_DEPTH,
 		maxLines: options.maxLines ?? 40,
 		commandHints: options.commandHints ?? false,
 	});

package/dist/builtin/subagents/src/runs/shared/pi-args.ts

@@ -13,10 +13,11 @@ import { encodeNestedPathEnv, parseNestedPathEnv, type NestedPathEntry } from ".
 import { resolveMcpDirectToolNames } from "./mcp-direct-tool-allowlist.ts";
 import { STRUCTURED_OUTPUT_CAPTURE_ENV, STRUCTURED_OUTPUT_SCHEMA_ENV } from "./structured-output.ts";
 import type { JsonSchemaObject } from "../../shared/types.ts";
+import { MAX_SUBAGENT_NESTING_DEPTH } from "../../shared/types-runtime.ts";
 
 const THINKING_LEVELS = ["off", "minimal", "low", "medium", "high", "xhigh"];
 const TASK_ARG_LIMIT = 8000;
-export const SUBAGENT_PARENT_MAX_DEPTH = 3;
+export const SUBAGENT_PARENT_MAX_DEPTH = MAX_SUBAGENT_NESTING_DEPTH;
 export const PROMPT_RUNTIME_EXTENSION_PATH = path.join(path.dirname(fileURLToPath(import.meta.url)), "subagent-prompt-runtime.ts");
 const ENV_PREFIX = APP_NAME.toUpperCase();
 export const FANOUT_CHILD_EXTENSION_PATH = path.join(path.dirname(fileURLToPath(import.meta.url)), "..", "..", "extension", "fanout-child.ts");

package/dist/builtin/subagents/src/runs/shared/subagent-prompt-runtime.ts

@@ -31,6 +31,7 @@ export const CHILD_FANOUT_BOUNDARY_INSTRUCTIONS = [
 const PARENT_ONLY_CUSTOM_MESSAGE_TYPES = new Set([
 	"subagent-orchestration-instructions",
 	"subagent-slash-result",
+	"subagent-slash-text-result",
 	"subagent-notify",
 	"subagent_control_notice",
 	"subagent-control",
@@ -130,14 +131,15 @@ function stripAssistantSubagentToolCallBlocks(message: unknown): unknown | undef
 }
 
 export function stripParentOnlySubagentMessages(messages: unknown[]): unknown[] {
+	const preserveCurrentFanoutToolHistory = process.env[SUBAGENT_FANOUT_CHILD_ENV] === "1";
 	let changed = false;
 	const filtered: unknown[] = [];
 	for (const message of messages) {
-		if (isParentOnlySubagentMessage(message) || isSubagentToolResultMessage(message)) {
+		if (isParentOnlySubagentMessage(message) || (!preserveCurrentFanoutToolHistory && isSubagentToolResultMessage(message))) {
 			changed = true;
 			continue;
 		}
-		const stripped = stripAssistantSubagentToolCallBlocks(message);
+		const stripped = preserveCurrentFanoutToolHistory ? message : stripAssistantSubagentToolCallBlocks(message);
 		if (stripped === undefined) {
 			changed = true;
 			continue;

package/dist/builtin/subagents/src/shared/types-async.ts

@@ -230,6 +230,7 @@ export interface SubagentState {
 	baseCwd: string;
 	currentSessionId: string | null;
 	asyncJobs: Map<string, AsyncJobState>;
+	subagentInProgress?: boolean;
 	foregroundRuns?: Map<string, ForegroundResumeRun>;
 	foregroundControls: Map<string, {
 		runId: string;

package/dist/builtin/subagents/src/shared/types-depth.ts

@@ -4,7 +4,7 @@
 
 import type { ExtensionContext } from "@bastani/atomic";
 import { APP_NAME, getEnvValue, WORKFLOW_STAGE_SUBAGENT_GUARD_ENV } from "@bastani/atomic";
-import { DEFAULT_SUBAGENT_MAX_DEPTH } from "./types-runtime.ts";
+import { DEFAULT_SUBAGENT_MAX_DEPTH, MAX_SUBAGENT_NESTING_DEPTH } from "./types-runtime.ts";
 
 const ENV_PREFIX = APP_NAME.toUpperCase();
 const SUBAGENT_MAX_DEPTH_ENV = `${ENV_PREFIX}_SUBAGENT_MAX_DEPTH`;
@@ -16,7 +16,7 @@ export { WORKFLOW_STAGE_SUBAGENT_GUARD_ENV };
 export function normalizeMaxSubagentDepth(value: unknown): number | undefined {
 	const parsed = typeof value === "number" ? value : typeof value === "string" ? Number(value) : NaN;
 	if (!Number.isInteger(parsed) || parsed < 0) return undefined;
-	return parsed;
+	return Math.min(parsed, MAX_SUBAGENT_NESTING_DEPTH);
 }
 
 export function resolveCurrentMaxSubagentDepth(configMaxDepth?: number): number {
@@ -45,9 +45,9 @@ export function resolveWorkflowStageMaxSubagentDepth(
 ): number {
 	const maxDepth = resolveCurrentMaxSubagentDepth(configMaxDepth);
 	return isWorkflowStageOrchestrationContext(ctx)
-		// Workflow stages use the same two-hop default as main chat. A 0-depth
-		// constraint still preserves one child-subagent hop so configured workflow
-		// stages can delegate at least once.
+		// Workflow stages receive an explicit host constraint, clamped by the
+		// inherited/global nesting ceiling. A 0-depth workflow constraint still
+		// preserves one child-subagent hop so configured stages can delegate once.
 		? Math.min(maxDepth, Math.max(1, ctx.orchestrationContext?.constraints.maxSubagentDepth ?? 1))
 		: maxDepth;
 }

package/dist/builtin/subagents/src/shared/types-runtime.ts

@@ -93,7 +93,8 @@ export const SLASH_SUBAGENT_UPDATE_EVENT = "subagent:slash:update";
 export const SLASH_SUBAGENT_CANCEL_EVENT = "subagent:slash:cancel";
 export const POLL_INTERVAL_MS = 250;
 export const MAX_WIDGET_JOBS = 4;
-export const DEFAULT_SUBAGENT_MAX_DEPTH = 2;
+export const MAX_SUBAGENT_NESTING_DEPTH = 5;
+export const DEFAULT_SUBAGENT_MAX_DEPTH = MAX_SUBAGENT_NESTING_DEPTH;
 export const SUBAGENT_ACTIONS = ["list", "get", "create", "update", "delete", "status", "interrupt", "resume", "doctor"] as const;
 
 export const DEFAULT_FORK_PREAMBLE =

package/dist/builtin/subagents/src/slash/prompt-template-bridge.ts

@@ -82,6 +82,7 @@ interface PromptTemplateBridgeResult {
 			exitCode?: number;
 			error?: string;
 			model?: string;
+			toolCalls?: Array<{ text?: string; expandedText?: string }>;
 		}>;
 		progress?: Array<{
 			index?: number;
@@ -147,10 +148,13 @@ function parsePromptTemplateRequest(data: unknown): PromptTemplateDelegationRequ
 	if (!hasSingle && tasks.length === 0) return undefined;
 
 	const fallbackTask = tasks[0];
+	const agent = hasSingle ? value.agent : fallbackTask?.agent;
+	const task = hasSingle ? value.task : fallbackTask?.task;
+	if (!agent || !task) return undefined;
 	return {
 		requestId: value.requestId,
-		agent: hasSingle ? value.agent : fallbackTask!.agent,
-		task: hasSingle ? value.task : fallbackTask!.task,
+		agent,
+		task,
 		...(tasks.length > 0 ? { tasks } : {}),
 		context: value.context,
 		model: value.model,
@@ -209,13 +213,31 @@ function resolveProgressModel(
 	return firstWithModel?.model;
 }
 
-function buildDelegationMessages(result: { messages?: unknown[]; finalOutput?: string }, fallbackText?: string): unknown[] {
+function toolCallSummaryText(summary: { text?: string; expandedText?: string }): string | undefined {
+	const text = typeof summary.expandedText === "string" && summary.expandedText.trim().length > 0
+		? summary.expandedText.trim()
+		: typeof summary.text === "string"
+			? summary.text.trim()
+			: "";
+	return text || undefined;
+}
+
+function buildDelegationMessages(
+	result: { messages?: unknown[]; finalOutput?: string; toolCalls?: Array<{ text?: string; expandedText?: string }> },
+	fallbackText?: string,
+): unknown[] {
 	if (Array.isArray(result.messages) && result.messages.length > 0) return result.messages;
+	const toolCallSummaries = (result.toolCalls ?? []).flatMap((summary) => {
+		const text = toolCallSummaryText(summary);
+		return text ? [`- ${text}`] : [];
+	});
+	const toolCallText = toolCallSummaries.length > 0 ? `Tool calls:\n${toolCallSummaries.join("\n")}` : undefined;
 	const text = typeof result.finalOutput === "string" && result.finalOutput.trim().length > 0
 		? result.finalOutput.trim()
 		: fallbackText;
-	if (!text) return [];
-	return [{ role: "assistant", content: [{ type: "text", text }] }];
+	const contentText = [toolCallText, text].filter((part): part is string => Boolean(part)).join("\n\n");
+	if (!contentText) return [];
+	return [{ role: "assistant", content: [{ type: "text", text: contentText }] }];
 }
 
 function toDelegationUpdate(requestId: string, update: PromptTemplateBridgeResult): PromptTemplateDelegationUpdate | undefined {

package/dist/builtin/subagents/src/tui/render-event-formatting.ts

@@ -1,5 +1,5 @@
 import * as path from "node:path";
-import type { AsyncJobState, AsyncJobStep, NestedRunSummary, NestedStepSummary } from "../shared/types.ts";
+import { MAX_SUBAGENT_NESTING_DEPTH, type AsyncJobState, type AsyncJobStep, type NestedRunSummary, type NestedStepSummary } from "../shared/types.ts";
 import { flatToLogicalStepIndex } from "../runs/background/parallel-groups.ts";
 import { formatDuration, formatModelThinking, shortenPath } from "../shared/formatters.ts";
 import { formatNestedAggregate } from "../runs/shared/nested-render.ts";
@@ -223,7 +223,7 @@ export function formatNestedWidgetLines(children: NestedRunSummary[] | undefined
 		return aggregate ? [theme.fg("dim", `↳ ${aggregate}`)] : [];
 	}
 	const lines: string[] = [];
-	const maxDepth = 2;
+	const maxDepth = MAX_SUBAGENT_NESTING_DEPTH;
 	const append = (items: NestedRunSummary[] | undefined, depth: number, prefix: string): void => {
 		if (!items?.length || lines.length >= lineBudget) return;
 		if (depth > maxDepth) {

package/dist/builtin/subagents/src/tui/render-layout.ts

@@ -66,16 +66,22 @@ export function truncLine(text: string, maxWidth: number): string {
 	return result + activeStyles.join("") + "…";
 }
 
-const RUNNING_FRAMES = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"];
+export const RUNNING_FRAMES = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"];
 
 /**
  * Spinner cadence (ms per frame). The running glyph is derived from wall-clock
  * time so every active spinner advances smoothly and in lockstep, independent
  * of how often (or how irregularly) progress data updates arrive. The animation
  * timers below only schedule re-renders; the displayed frame always comes from
- * the clock. This fixes the frozen/stuttering spinner from issue #1084 while
- * keeping per-frame diffs to a single glyph cell so the differential renderer
- * never needs a full-clear (no flicker).
+ * the clock. This fixes the frozen/stuttering spinner from issue #1084.
+ *
+ * IMPORTANT: a wall-clock spinner only stays flicker-free for widgets pinned to
+ * the bottom of the buffer (e.g. the below-editor async widget), where every
+ * tick stays inside the viewport. Content rendered into chat scrollback (live
+ * foreground subagent results) can scroll above the viewport fold; there, even
+ * a single-cell spinner diff forces pi-tui into a destructive full-screen +
+ * scrollback clear on every tick. Such surfaces must NOT animate on a timer —
+ * see pulseGlyph(), which is advanced once per real progress update instead.
  */
 export const RUNNING_ANIMATION_MS = 80;
 
@@ -106,6 +112,23 @@ export function runningGlyph(seed?: number, now?: number): string {
 	return RUNNING_FRAMES[Math.abs(animatedSeed) % RUNNING_FRAMES.length]!;
 }
 
+export const PULSE_FRAMES = ["·", "•", "●", "•"];
+
+/**
+ * Activity "heartbeat" glyph for live foreground subagent results. Unlike
+ * runningGlyph(), the frame is NOT derived from wall-clock time: the caller
+ * advances `frame` exactly once per real progress update (see
+ * renderLiveSubagentResult). With no animation timer, the only line diffs this
+ * produces coincide with progress data that genuinely changed, so the pulse can
+ * live in chat scrollback (above or below the fold) without ever triggering
+ * pi-tui's full-screen/scrollback clear. Returns a steady breathing dot that
+ * grows and settles as the subagent reports activity.
+ */
+export function pulseGlyph(frame?: number): string {
+	const index = Number.isFinite(frame) ? Math.abs(Math.trunc(frame as number)) : 0;
+	return PULSE_FRAMES[index % PULSE_FRAMES.length]!;
+}
+
 export function progressRunningSeed(progress: ProgressSeedSource | undefined): number | undefined {
 	if (!progress) return undefined;
 	return runningSeed(

package/dist/builtin/subagents/src/tui/render-result-animation.ts

@@ -1,56 +1,47 @@
-import { RUNNING_ANIMATION_MS } from "./render-layout.ts";
-
 type ResultAnimationTimer = ReturnType<typeof setInterval>;
 
 export interface SubagentResultRenderState {
 	subagentResultAnimationTimer?: ResultAnimationTimer;
+	subagentResultAnimationCleanup?: () => void;
 	subagentResultSnapshotKey?: string;
 	/** Stable semantic/content timestamp used for durations and activity text. */
 	subagentResultSnapshotNow?: number;
-	/** Timer-driven timestamp used only for spinner glyph frames. */
-	subagentResultSpinnerFrameNow?: number;
+	/** Monotonic pulse frame, advanced once per progress update (no timer). */
+	subagentResultPulseFrame?: number;
 }
 
 export type ResultAnimationContext = {
 	state: SubagentResultRenderState;
 	invalidate: () => void;
 };
-type LegacyResultAnimationContext = { state: { subagentResultAnimationTimer?: ResultAnimationTimer } };
-
-const activeResultAnimationTimers = new Map<ResultAnimationTimer, SubagentResultRenderState>();
+type LegacyResultAnimationContext = {
+	state: {
+		subagentResultAnimationTimer?: ResultAnimationTimer;
+		subagentResultAnimationCleanup?: () => void;
+	};
+};
 
+/**
+ * Legacy safety net for render state objects created by earlier timer-driven
+ * foreground result rendering. New code never schedules result timers, but
+ * clearing the field prevents a stale interval from surviving across upgrades.
+ */
 export function clearResultAnimationTimer(context: LegacyResultAnimationContext): void {
 	const timer = context.state.subagentResultAnimationTimer;
-	if (timer) {
-		clearInterval(timer);
-		activeResultAnimationTimers.delete(timer);
-	}
+	if (timer) clearInterval(timer);
 	context.state.subagentResultAnimationTimer = undefined;
+	context.state.subagentResultAnimationCleanup = undefined;
 }
 
-export function clearLegacyResultAnimationTimer(context: LegacyResultAnimationContext): void {
-	clearResultAnimationTimer(context);
+export function advanceResultPulseFrame(frame: number | undefined): number {
+	return (frame ?? 0) + 1;
 }
 
-export function ensureResultAnimation(context: ResultAnimationContext): void {
-	if (context.state.subagentResultAnimationTimer) return;
-	const timer = setInterval(() => {
-		context.state.subagentResultSpinnerFrameNow = Date.now();
-		try {
-			context.invalidate();
-		} catch {
-			clearResultAnimationTimer(context);
-		}
-	}, RUNNING_ANIMATION_MS);
-	timer.unref?.();
-	context.state.subagentResultAnimationTimer = timer;
-	activeResultAnimationTimers.set(timer, context.state);
+export function clearLegacyResultAnimationTimer(context: LegacyResultAnimationContext): void {
+	clearResultAnimationTimer(context);
 }
 
 export function stopResultAnimations(): void {
-	for (const [timer, state] of activeResultAnimationTimers) {
-		clearInterval(timer);
-		if (state.subagentResultAnimationTimer === timer) state.subagentResultAnimationTimer = undefined;
-	}
-	activeResultAnimationTimers.clear();
+	// Retained for extension teardown compatibility; result rendering no longer
+	// registers global animation timers.
 }

package/dist/builtin/subagents/src/tui/render-result-compact.ts

@@ -2,7 +2,7 @@ import { Container, Text, type Component } from "@earendil-works/pi-tui";
 import type { AgentProgress, AsyncJobStep, Details } from "../shared/types.ts";
 import { shortenPath } from "../shared/formatters.ts";
 import { getSingleResultOutput } from "../shared/utils.ts";
-import { getTermWidth, progressRunningSeed, runningGlyph, runningSeed, truncLine, type Theme } from "./render-layout.ts";
+import { getTermWidth, pulseGlyph, truncLine, type Theme } from "./render-layout.ts";
 import {
 	buildLiveStatusLine,
 	compactCurrentActivity,
@@ -25,7 +25,7 @@ import {
 } from "./render-chain-graph.ts";
 import { modelThinkingBadge, widgetStepGlyph, widgetStepStatus } from "./render-event-formatting.ts";
 
-export function renderSingleCompact(d: Details, r: Details["results"][number], theme: Theme, now?: number, spinnerNow?: number): Component {
+export function renderSingleCompact(d: Details, r: Details["results"][number], theme: Theme, now?: number, pulseFrame?: number): Component {
 	const output = r.truncation?.text || getSingleResultOutput(r);
 	const progress = r.progress || r.progressSummary;
 	const isRunning = r.progress?.status === "running";
@@ -37,7 +37,7 @@ export function renderSingleCompact(d: Details, r: Details["results"][number], t
 	const c = new Container();
 	const width = getTermWidth() - 4;
 	const modelDisplay = modelThinkingBadge(theme, r.model, undefined, r.fastMode);
-	c.addChild(new Text(truncLine(`${resultGlyph(r, output, theme, isRunning, progressRunningSeed(r.progress ?? r.progressSummary), spinnerNow ?? now)} ${theme.fg("toolTitle", theme.bold(r.agent))}${modelDisplay}${contextBadge}${stats ? ` ${theme.fg("dim", "·")} ${stats}` : ""}`, width), 0, 0));
+	c.addChild(new Text(truncLine(`${resultGlyph(r, output, theme, isRunning, pulseFrame)} ${theme.fg("toolTitle", theme.bold(r.agent))}${modelDisplay}${contextBadge}${stats ? ` ${theme.fg("dim", "·")} ${stats}` : ""}`, width), 0, 0));
 
 	if (isRunning && r.progress) {
 		const progressSnapshotNow = snapshotNowForProgress(r.progress, now);
@@ -61,7 +61,7 @@ export function renderSingleCompact(d: Details, r: Details["results"][number], t
 	return c;
 }
 
-export function renderMultiCompact(d: Details, theme: Theme, now?: number, spinnerNow?: number): Component {
+export function renderMultiCompact(d: Details, theme: Theme, now?: number, pulseFrame?: number): Component {
 	const hasRunning = d.progress?.some((p) => p.status === "running")
 		|| d.results.some((r) => r.progress?.status === "running")
 		|| workflowGraphHasStatus(d, ["running"]);
@@ -87,7 +87,7 @@ export function renderMultiCompact(d: Details, theme: Theme, now?: number, spinn
 	const itemTitle = multiLabel.itemTitle;
 	const stats = statJoin(theme, [multiLabel.headerLabel, formatProgressStats(theme, totalSummary, true, now)]);
 	const glyph = hasRunning
-		? theme.fg("accent", runningGlyph(runningSeed(progressRunningSeed(totalSummary), d.currentStepIndex), spinnerNow ?? now))
+		? theme.fg("accent", pulseGlyph(pulseFrame))
 		: failed
 			? theme.fg("error", "✗")
 			: paused
@@ -133,7 +133,7 @@ export function renderMultiCompact(d: Details, theme: Theme, now?: number, spinn
 		const rPending = rProg && "status" in rProg && rProg.status === "pending";
 		const stepNumber = r.progress?.index !== undefined ? r.progress.index + 1 : progressFromArray?.index !== undefined ? progressFromArray.index + 1 : i + 1;
 		const stepStats = formatProgressStats(theme, rProg, true, now);
-		const glyph = rPending ? theme.fg("dim", "◦") : resultGlyph(r, output, theme, rRunning, progressRunningSeed(rProg), spinnerNow ?? now);
+		const glyph = rPending ? theme.fg("dim", "◦") : resultGlyph(r, output, theme, rRunning, pulseFrame);
 		const pendingLabel = rPending ? ` ${theme.fg("dim", "· pending")}` : "";
 		const stepLabel = resultRowLabel(d, multiLabel, i, stepNumber);
 		const line = `${glyph} ${stepLabel}: ${themeBold(theme, agentName)}${stepStats ? ` ${theme.fg("dim", "·")} ${stepStats}` : ""}${pendingLabel}`;