@bastani/atomic 0.9.9 → 0.9.10

package/dist/builtin/subagents/skills/subagent/SKILL.md

@@ -419,7 +419,7 @@ subagent({
 })
 ```
 
-`worktree: true` gives each parallel task its own git worktree branched from HEAD. This requires a clean git state and is mainly for intentionally parallel writer workflows. If you want one writer thread and several advisory readers, prefer a single-writer pattern instead — only `debugger` and `code-simplifier` write, so co-locating them with read-only specialists in the same worktree is safe.
+`worktree: true` gives each parallel task its own `worktree-*` branch under the canonical main root's `.atomic/worktrees/`, using the remote default branch when available and `HEAD` otherwise. This requires a clean git state and is mainly for intentionally parallel writer workflows. If you want one writer thread and several advisory readers, prefer a single-writer pattern instead — only `debugger` and `code-simplifier` write, so co-locating them with read-only specialists in the same worktree is safe.
 
 ## Subagent + Intercom Coordination
 

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

@@ -3,7 +3,7 @@ import * as fs from "node:fs";
 import * as os from "node:os";
 import * as path from "node:path";
 import type { AgentToolResult } from "@earendil-works/pi-agent-core";
-import { APP_NAME, getEnvValue } from "@bastani/atomic";
+import { APP_NAME, getEnvValue, keyHintIfBound } from "@bastani/atomic";
 import { type ExtensionAPI, type ExtensionContext, type ToolDefinition } from "@bastani/atomic";
 import { Box, Container, Spacer, Text, truncateToWidth, visibleWidth, wrapTextWithAnsi, type Component } from "@earendil-works/pi-tui";
 import { discoverAgents } from "../agents/agents.ts";
@@ -23,6 +23,7 @@ import registerFanoutChildSubagentExtension from "./fanout-child.ts";
 import { formatDuration, shortenPath } from "../shared/formatters.ts";
 import { loadConfig } from "./config.ts";
 import { DEFAULT_PROMPT_GUIDANCE } from "./prompt-guidance.ts";
+import { parseSubagentNotifyContent } from "./notification-content.ts";
 import { SUBAGENT_TOOL_DESCRIPTION } from "./tool-description.ts";
 export { SUBAGENT_TOOL_DESCRIPTION } from "./tool-description.ts";
 import { type Details, type SubagentState, ASYNC_DIR, DEFAULT_ARTIFACT_CONFIG, RESULTS_DIR, SLASH_RESULT_TYPE, SUBAGENT_ASYNC_COMPLETE_EVENT, SUBAGENT_ASYNC_STARTED_EVENT, SUBAGENT_CONTROL_EVENT } from "../shared/types.ts";
@@ -98,36 +99,39 @@ function createSlashResultComponent(
 	};
 	return container;
 }
-function parseSubagentNotifyContent(content: string): SubagentNotifyDetails | undefined {
-	const lines = content.split("\n");
-	const header = lines[0] ?? "";
-	const match = header.match(/^Background task (completed|failed|paused): \*\*(.+?)\*\*(?:\s+(\([^)]*\)))?$/);
-	if (!match) return undefined;
-	const body = lines.slice(2);
-	let sessionIndex = -1;
-	for (let i = body.length - 1; i >= 1; i--) {
-		if (body[i - 1]?.trim() === "" && /^(Session|Session file|Session share error):\s+/.test(body[i]!)) {
-			sessionIndex = i;
-			break;
-		}
+export function renderSubagentNotification(
+	message: { content: unknown; details?: unknown },
+	options: { expanded: boolean },
+	theme: ExtensionContext["ui"]["theme"],
+): Text {
+	const content = typeof message.content === "string" ? message.content : "";
+	const details = (message.details as SubagentNotifyDetails | undefined) ?? parseSubagentNotifyContent(content);
+	if (!details) return new Text(content, 0, 0);
+	const icon = details.status === "completed"
+		? theme.fg("success", "✓")
+		: details.status === "paused"
+			? theme.fg("warning", "■")
+			: theme.fg("error", "✗");
+	const parts: string[] = [];
+	if (details.taskInfo) parts.push(details.taskInfo);
+	if (details.durationMs !== undefined) parts.push(formatDuration(details.durationMs));
+	let text = `${icon} ${theme.bold(details.agent)} ${theme.fg("dim", details.status)}`;
+	if (parts.length > 0) text += ` ${theme.fg("dim", "·")} ${parts.map((part) => theme.fg("dim", part)).join(` ${theme.fg("dim", "·")} `)}`;
+	const trimmedPreview = details.resultPreview.trim();
+	const previewLines = options.expanded
+		? trimmedPreview.split("\n").filter((line) => line.trim())
+		: [trimmedPreview.split("\n", 1)[0] ?? ""].filter((line) => line.trim());
+	for (const line of previewLines.length > 0 ? previewLines : ["(no output)"]) {
+		text += `\n  ${theme.fg("dim", `⎿  ${line}`)}`;
 	}
-	const sessionLine = sessionIndex >= 0 ? body[sessionIndex] : undefined;
-	const resultLines = sessionIndex >= 0 ? body.slice(0, sessionIndex) : body;
-	const resultPreview = resultLines.join("\n").trim() || "(no output)";
-	let sessionLabel: string | undefined;
-	let sessionValue: string | undefined;
-	if (sessionLine) {
-		const separator = sessionLine.indexOf(":");
-		sessionLabel = sessionLine.slice(0, separator).toLowerCase();
-		sessionValue = sessionLine.slice(separator + 1).trim();
+	if (!options.expanded && trimmedPreview.includes("\n")) {
+		const expandHint = keyHintIfBound("app.tools.expand", "full notification");
+		if (expandHint) text += `\n  ${expandHint}`;
 	}
-	return {
-		agent: match[2]!,
-		status: match[1] as SubagentNotifyDetails["status"],
-		...(match[3] ? { taskInfo: match[3] } : {}),
-		resultPreview,
-		...(sessionLabel && sessionValue ? { sessionLabel, sessionValue } : {}),
-	};
+	if (details.sessionLabel && details.sessionValue) {
+		text += `\n  ${theme.fg("muted", `${details.sessionLabel}: ${shortenPath(details.sessionValue)}`)}`;
+	}
+	return new Text(text, 0, 0);
 }
 class SubagentControlNoticeComponent implements Component {
 	constructor(
@@ -197,7 +201,7 @@ export default function registerSubagentExtension(pi: ExtensionAPI): void {
 		registrationFailureCleanups.push(() => maintenance.stop());
 		maintenance.startResultWatcherDeferred();
 		maintenance.primeExistingResultsDeferred();
-		const { ensurePoller, handleStarted, handleComplete, resetJobs, hydrateActiveJobs } = createAsyncJobTracker(pi, state, ASYNC_DIR);
+		const { ensurePoller, handleStarted, handleComplete, resetJobs, hydrateActiveJobsDeferred } = createAsyncJobTracker(pi, state, ASYNC_DIR);
 		const executor = createSubagentExecutor({
 			pi,
 			state,
@@ -213,35 +217,7 @@ export default function registerSubagentExtension(pi: ExtensionAPI): void {
 			if (!details) return undefined;
 			return createSlashResultComponent(details, options, theme, pi);
 		});
-		pi.registerMessageRenderer<SubagentNotifyDetails>("subagent-notify", (message, options, theme) => {
-			const content = typeof message.content === "string" ? message.content : "";
-			const details = (message.details as SubagentNotifyDetails | undefined) ?? parseSubagentNotifyContent(content);
-			if (!details) return new Text(content, 0, 0);
-			const icon = details.status === "completed"
-				? theme.fg("success", "✓")
-				: details.status === "paused"
-					? theme.fg("warning", "■")
-					: theme.fg("error", "✗");
-			const parts: string[] = [];
-			if (details.taskInfo) parts.push(details.taskInfo);
-			if (details.durationMs !== undefined) parts.push(formatDuration(details.durationMs));
-			let text = `${icon} ${theme.bold(details.agent)} ${theme.fg("dim", details.status)}`;
-			if (parts.length > 0) text += ` ${theme.fg("dim", "·")} ${parts.map((part) => theme.fg("dim", part)).join(` ${theme.fg("dim", "·")} `)}`;
-			const trimmedPreview = details.resultPreview.trim();
-			const previewLines = options.expanded
-				? trimmedPreview.split("\n").filter((line) => line.trim())
-				: [trimmedPreview.split("\n", 1)[0] ?? ""].filter((line) => line.trim());
-			for (const line of previewLines.length > 0 ? previewLines : ["(no output)"]) {
-				text += `\n  ${theme.fg("dim", `⎿  ${line}`)}`;
-			}
-			if (!options.expanded && trimmedPreview.includes("\n")) {
-				text += `\n  ${theme.fg("dim", "ctrl+o full notification")}`;
-			}
-			if (details.sessionLabel && details.sessionValue) {
-				text += `\n  ${theme.fg("muted", `${details.sessionLabel}: ${shortenPath(details.sessionValue)}`)}`;
-			}
-			return new Text(text, 0, 0);
-		});
+		pi.registerMessageRenderer<SubagentNotifyDetails>("subagent-notify", renderSubagentNotification);
 		pi.registerMessageRenderer<SubagentControlMessageDetails>(SUBAGENT_CONTROL_MESSAGE_TYPE, (message, _options, theme) => {
 			const details = message.details as SubagentControlMessageDetails | undefined;
 			if (!details?.event) return undefined;
@@ -422,7 +398,7 @@ export default function registerSubagentExtension(pi: ExtensionAPI): void {
 			if (!lifecycle.isCurrent() || event.toolName !== "subagent") return;
 			if (!ctx.hasUI) return;
 			state.lastUiContext = ctx;
-			hydrateActiveJobs(ctx);
+			hydrateActiveJobsDeferred(ctx);
 			if (state.asyncJobs.size > 0) ensurePoller();
 		});
 		const cleanupSessionArtifacts = (ctx: ExtensionContext) => {
@@ -435,7 +411,7 @@ export default function registerSubagentExtension(pi: ExtensionAPI): void {
 			cleanupSessionArtifacts(ctx);
 			clearPendingForegroundControlNotices(state);
 			resetJobs(ctx);
-			hydrateActiveJobs(ctx);
+			hydrateActiveJobsDeferred(ctx);
 			restoreSlashFinalSnapshots(ctx.sessionManager.getEntries(), pi);
 			maintenance.primeExistingResultsDeferred();
 		};

package/dist/builtin/subagents/src/extension/notification-content.ts

@@ -0,0 +1,80 @@
+import type { SubagentNotifyDetails } from "../runs/background/notify.ts";
+
+const HEADER_PREFIXES = [
+	["Background task completed: **", "completed"],
+	["Background task failed: **", "failed"],
+	["Background task paused: **", "paused"],
+] as const;
+
+function isHeaderLineTerminator(character: string): boolean {
+	return character === "\r" || character === "\u2028" || character === "\u2029";
+}
+
+function isWhitespace(character: string | undefined): boolean {
+	return character !== undefined && character.trim() === "";
+}
+
+function parseHeader(header: string): Pick<SubagentNotifyDetails, "agent" | "status" | "taskInfo"> | undefined {
+	const matchedPrefix = HEADER_PREFIXES.find(([prefix]) => header.startsWith(prefix));
+	if (!matchedPrefix) return undefined;
+	const [prefix, status] = matchedPrefix;
+	const suffix = header.slice(prefix.length);
+
+	if (suffix.endsWith("**")) {
+		const agent = suffix.slice(0, -2);
+		if (!agent || [...agent].some(isHeaderLineTerminator)) return undefined;
+		return { agent, status };
+	}
+	if (!suffix.endsWith(")")) return undefined;
+
+	const lastInteriorClose = suffix.lastIndexOf(")", suffix.length - 2);
+	let index = 1;
+	while (index < suffix.length - 1) {
+		if (suffix[index] !== "*" || suffix[index + 1] !== "*") {
+			index += 1;
+			continue;
+		}
+		let taskStart = index + 2;
+		if (!isWhitespace(suffix[taskStart])) {
+			index += 1;
+			continue;
+		}
+		while (isWhitespace(suffix[taskStart])) taskStart += 1;
+		if (suffix[taskStart] === "(" && taskStart > lastInteriorClose) {
+			const agent = suffix.slice(0, index);
+			if ([...agent].some(isHeaderLineTerminator)) return undefined;
+			return { agent, status, taskInfo: suffix.slice(taskStart) };
+		}
+		index = taskStart;
+	}
+	return undefined;
+}
+
+export function parseSubagentNotifyContent(content: string): SubagentNotifyDetails | undefined {
+	const lines = content.split("\n");
+	const parsedHeader = parseHeader(lines[0] ?? "");
+	if (!parsedHeader) return undefined;
+	const body = lines.slice(2);
+	let sessionIndex = -1;
+	for (let i = body.length - 1; i >= 1; i--) {
+		if (body[i - 1]?.trim() === "" && /^(Session|Session file|Session share error):\s+/.test(body[i]!)) {
+			sessionIndex = i;
+			break;
+		}
+	}
+	const sessionLine = sessionIndex >= 0 ? body[sessionIndex] : undefined;
+	const resultLines = sessionIndex >= 0 ? body.slice(0, sessionIndex) : body;
+	const resultPreview = resultLines.join("\n").trim() || "(no output)";
+	let sessionLabel: string | undefined;
+	let sessionValue: string | undefined;
+	if (sessionLine) {
+		const separator = sessionLine.indexOf(":");
+		sessionLabel = sessionLine.slice(0, separator).toLowerCase();
+		sessionValue = sessionLine.slice(separator + 1).trim();
+	}
+	return {
+		...parsedHeader,
+		resultPreview,
+		...(sessionLabel && sessionValue ? { sessionLabel, sessionValue } : {}),
+	};
+}

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

@@ -54,6 +54,10 @@ const MaxOutputSchema = Type.Object({
 	lines: Type.Optional(Type.Number()),
 }, { additionalProperties: false });
 
+const GroupSchema = Type.Union([Type.String(), Type.Boolean()], {
+	description: "Intercom group for spawned children. A named string joins that group; boolean `true` or the trimmed, case-insensitive string sentinel `true`/`auto` auto-generates one shared UUID group per parallel set. The names `true` and `auto` are reserved; use a different literal group name. Defaults to the current session/stage's group. Only applied when the child has intercom access; contact_supervisor still reaches the supervisor across groups.",
+});
+
 const TaskItem = Type.Object({
 	agent: Type.String(), 
 	task: Type.String(), 
@@ -65,6 +69,7 @@ const TaskItem = Type.Object({
 	progress: Type.Optional(Type.Boolean({ description: "Enable progress.md tracking for this task" })),
 	model: Type.Optional(Type.String({ description: "Override model for this task (e.g. 'google/gemini-3-pro')" })),
 	skill: Type.Optional(SkillOverride),
+	group: Type.Optional(GroupSchema),
 });
 
 // Parallel task item (within a parallel step)
@@ -83,6 +88,7 @@ const ParallelTaskSchema = Type.Object({
 	progress: Type.Optional(Type.Boolean({ description: "Enable progress.md tracking in {chain_dir}" })),
 	skill: Type.Optional(SkillOverride),
 	model: Type.Optional(Type.String({ description: "Override model for this task" })),
+	group: Type.Optional(GroupSchema),
 });
 
 const DynamicExpandSchema = Type.Object({
@@ -109,6 +115,7 @@ const DynamicParallelTemplateSchema = Type.Object({
 	progress: Type.Optional(Type.Boolean({ description: "Enable progress.md tracking in {chain_dir}" })),
 	skill: Type.Optional(SkillOverride),
 	model: Type.Optional(Type.String({ description: "Override model for this task" })),
+	group: Type.Optional(GroupSchema),
 }, { additionalProperties: false });
 
 const DynamicCollectSchema = Type.Object({
@@ -147,6 +154,7 @@ const ChainItem = Type.Object({
 	worktree: Type.Optional(Type.Boolean({
 		description: "Create isolated git worktrees for each parallel task."
 	})),
+	group: Type.Optional(GroupSchema),
 }, {
 	description: "Chain step: use {agent, task?, ...} for sequential, {parallel: [...]} for static concurrent execution, or {expand, parallel: {...}, collect} for dynamic fanout.",
 	additionalProperties: false,
@@ -203,6 +211,7 @@ export const SubagentParams = Type.Object({
 		description: `PARALLEL mode: [{agent, task, count?, output?, outputMode?, reads?, progress?}, ...]. Maximum ${MAX_PARALLEL_TASKS} tasks after count expansion.`,
 	})),
 	concurrency: Type.Optional(Type.Integer({ minimum: 1, description: "Top-level PARALLEL mode only: max concurrent tasks. Defaults to config.parallel.concurrency or 4." })),
+	group: Type.Optional(GroupSchema),
 	worktree: Type.Optional(Type.Boolean({
 		description: "Create isolated git worktrees for each parallel task. " +
 			"Prevents filesystem conflicts. Requires clean git state. " +

package/dist/builtin/subagents/src/extension/tool-description.ts

@@ -9,6 +9,7 @@ EXECUTION (use exactly ONE mode):
 • PARALLEL: { tasks: [{agent,task,count?,output?,reads?,progress?}, ...], concurrency?: number, worktree?: true } - independent concurrent tasks (worktree: isolate each task in a git worktree)
 • Optional context: { context: "fresh" | "fork" } (default: if any requested agent has defaultContext: "fork", the whole invocation uses fork; otherwise "fresh"; inspect agent defaults via { action: "list" })
 • async:true is selective for genuinely long-running/background work; foreground is appropriate when the parent needs the result before proceeding
+• group (string | true) sets the intercom group for spawned children so same-group subagents can intercom each other but stay isolated from other groups. Boolean true or the trimmed, case-insensitive string sentinel "true"/"auto" auto-generates one shared group per parallel set; those names are reserved and cannot be literal groups. Defaults to the current session/stage's group (subagents inherit their launching stage's group). Only applied when the child has intercom access; contact_supervisor still reaches the supervisor across groups.
 CHAIN TEMPLATE VARIABLES (use in task strings):
 • {task} - The original task/request from the user
 • {previous} - Text response from the previous step (empty for first step)

package/dist/builtin/subagents/src/intercom/supervisor-authorization.ts

@@ -0,0 +1,23 @@
+import type { IntercomEventBus } from "../shared/types.ts";
+
+export const SUBAGENT_SUPERVISOR_AUTHORIZATION_EVENT = "subagent:supervisor-authorization";
+
+export interface SupervisorAuthorization {
+	capability: string;
+	supervisorSessionId: string;
+	childName: string;
+}
+
+/** Ask the parent Intercom extension to mint a broker-issued child capability. */
+export async function requestSupervisorAuthorization(
+	events: IntercomEventBus | undefined,
+	childName: string | undefined,
+): Promise<SupervisorAuthorization | undefined> {
+	const normalizedChildName = childName?.trim();
+	if (!events || !normalizedChildName) return undefined;
+	const request: { childName: string; completion?: Promise<SupervisorAuthorization> } = {
+		childName: normalizedChildName,
+	};
+	events.emit(SUBAGENT_SUPERVISOR_AUTHORIZATION_EVENT, request);
+	return request.completion ? await request.completion : undefined;
+}

package/dist/builtin/subagents/src/runs/background/async-execution-chain.ts

@@ -54,6 +54,8 @@ export function executeAsyncChain(
 		controlConfig,
 		controlIntercomTarget,
 		childIntercomTarget,
+		supervisorAuthorizations,
+		dynamicSupervisorAuthorizations,
 		nestedRoute,
 	} = params;
 	const resultMode = params.resultMode ?? "chain";
@@ -292,6 +294,8 @@ export function executeAsyncChain(
 				controlConfig,
 				controlIntercomTarget,
 				childIntercomTargets,
+				supervisorAuthorizations,
+				dynamicSupervisorAuthorizations,
 				resultMode,
 				dynamicFanoutMaxItems: params.dynamicFanoutMaxItems,
 				workflowGraph,

package/dist/builtin/subagents/src/runs/background/async-execution-single.ts

@@ -47,6 +47,7 @@ export function executeAsyncSingle(
 		controlConfig,
 		controlIntercomTarget,
 		childIntercomTarget,
+		supervisorAuthorization,
 		nestedRoute,
 		spawnRunner = defaultSpawnRunner,
 	} = params;
@@ -159,6 +160,7 @@ export function executeAsyncSingle(
 				controlConfig,
 				controlIntercomTarget,
 				childIntercomTargets: childIntercomTarget ? [childIntercomTarget(agent, 0)] : undefined,
+				supervisorAuthorizations: supervisorAuthorization ? [supervisorAuthorization] : undefined,
 				resultMode: "single",
 				nestedRoute: nestedRoute ?? inheritedNestedRoute,
 				workflowStageSubagentGuard,

package/dist/builtin/subagents/src/runs/background/async-execution-types.ts

@@ -2,6 +2,7 @@ import type { ExtensionAPI, SessionWorkflowMetadata } from "@bastani/atomic";
 import type { AgentConfig } from "../../agents/agents.ts";
 import type { ChainStep } from "../../shared/settings.ts";
 import type { AvailableModelInfo } from "../shared/model-fallback.ts";
+import type { SupervisorAuthorization } from "../../intercom/supervisor-authorization.ts";
 import type {
 	ArtifactConfig,
 	Details,
@@ -44,6 +45,8 @@ export interface AsyncChainParams {
 	controlConfig?: ResolvedControlConfig;
 	controlIntercomTarget?: string;
 	childIntercomTarget?: (agent: string, index: number) => string | undefined;
+	supervisorAuthorizations?: Array<SupervisorAuthorization | undefined>;
+	dynamicSupervisorAuthorizations?: Record<number, SupervisorAuthorization[]>;
 	nestedRoute?: NestedRouteInfo;
 }
 
@@ -73,6 +76,7 @@ export interface AsyncSingleParams {
 	controlConfig?: ResolvedControlConfig;
 	controlIntercomTarget?: string;
 	childIntercomTarget?: (agent: string, index: number) => string | undefined;
+	supervisorAuthorization?: SupervisorAuthorization;
 	nestedRoute?: NestedRouteInfo;
 	/** Internal launch seam used by focused runtime tests. */
 	spawnRunner?: (

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

@@ -29,6 +29,9 @@ interface AsyncJobTrackerOptions {
 
 const ACTIVE_HYDRATION_STATES: Array<AsyncRunSummary["state"]> = ["queued", "running"];
 
+/** Only eagerly hydrate runs touched within the last 7 days; older runs stay on-demand. */
+const ACTIVE_HYDRATION_MAX_AGE_MS = 7 * 24 * 60 * 60 * 1000;
+
 function cwdMatches(summaryCwd: string | undefined, currentCwd: string | undefined): boolean {
 	return Boolean(summaryCwd && currentCwd && path.resolve(summaryCwd) === path.resolve(currentCwd));
 }
@@ -38,6 +41,31 @@ function shouldHydrateRunForCurrentUi(summary: AsyncRunSummary, currentSessionId
 	return cwdMatches(summary.cwd, currentCwd);
 }
 
+/**
+ * Extension contexts captured for timer-driven work (deferred hydration and
+ * state.lastUiContext) go stale after ctx.newSession(), ctx.fork(),
+ * ctx.switchSession(), or ctx.reload(); every accessor on a stale context
+ * throws. Probe defensively so an unref'd timer can never crash the host
+ * process with an unhandled stale-context error.
+ */
+function ctxHasUI(ctx: ExtensionContext | null | undefined): boolean {
+	if (!ctx) return false;
+	try {
+		return ctx.hasUI;
+	} catch {
+		return false;
+	}
+}
+
+function ctxCwd(ctx: ExtensionContext | null | undefined): string | undefined {
+	if (!ctx) return undefined;
+	try {
+		return ctx.cwd;
+	} catch {
+		return undefined;
+	}
+}
+
 function asyncRunSummaryToJobState(summary: AsyncRunSummary, existing?: AsyncJobState): AsyncJobState {
 	const chainStepCount = summary.chainStepCount ?? summary.steps.length;
 	const groups = normalizeParallelGroups(summary.parallelGroups, summary.steps.length, chainStepCount);
@@ -92,6 +120,7 @@ export function createAsyncJobTracker(pi: Pick<ExtensionAPI, "events">, state: S
 	handleComplete: (data: unknown) => void;
 	resetJobs: (ctx?: ExtensionContext) => void;
 	hydrateActiveJobs: (ctx?: ExtensionContext) => void;
+	hydrateActiveJobsDeferred: (ctx?: ExtensionContext) => void;
 } {
 	const completionRetentionMs = options.completionRetentionMs ?? 10000;
 	const pollIntervalMs = options.pollIntervalMs ?? POLL_INTERVAL_MS;
@@ -99,6 +128,18 @@ export function createAsyncJobTracker(pi: Pick<ExtensionAPI, "events">, state: S
 	const rerenderWidget = (ctx: ExtensionContext, jobs = Array.from(state.asyncJobs.values())) => {
 		renderWidget(ctx, jobs, pi);
 	};
+	/** Return the retained UI context when it is still usable; drop it once stale. */
+	const liveUiContext = (): ExtensionContext | undefined => {
+		const ctx = state.lastUiContext;
+		if (!ctx) return undefined;
+		try {
+			void ctx.hasUI;
+			return ctx;
+		} catch {
+			state.lastUiContext = null;
+			return undefined;
+		}
+	};
 	const cancelCleanup = (asyncId: string) => {
 		const existingTimer = state.cleanupTimers.get(asyncId);
 		if (!existingTimer) return;
@@ -110,8 +151,9 @@ export function createAsyncJobTracker(pi: Pick<ExtensionAPI, "events">, state: S
 		const timer = setTimeout(() => {
 			state.cleanupTimers.delete(asyncId);
 			state.asyncJobs.delete(asyncId);
-			if (state.lastUiContext) {
-				rerenderWidget(state.lastUiContext);
+			const uiCtx = liveUiContext();
+			if (uiCtx) {
+				rerenderWidget(uiCtx);
 			}
 		}, completionRetentionMs);
 		state.cleanupTimers.set(asyncId, timer);
@@ -176,7 +218,8 @@ export function createAsyncJobTracker(pi: Pick<ExtensionAPI, "events">, state: S
 		if (state.poller) return;
 		state.poller = setInterval(() => {
 			if (state.asyncJobs.size === 0) {
-				if (state.lastUiContext?.hasUI) rerenderWidget(state.lastUiContext, []);
+				const idleUiCtx = liveUiContext();
+				if (ctxHasUI(idleUiCtx)) rerenderWidget(idleUiCtx!, []);
 				if (state.poller) {
 					clearInterval(state.poller);
 					state.poller = null;
@@ -288,15 +331,17 @@ export function createAsyncJobTracker(pi: Pick<ExtensionAPI, "events">, state: S
 				if (widgetRenderKey(job) !== widgetStateBefore) widgetChanged = true;
 			}
 
-			if (widgetChanged && state.lastUiContext?.hasUI) rerenderWidget(state.lastUiContext);
+			const pollUiCtx = liveUiContext();
+			if (widgetChanged && ctxHasUI(pollUiCtx)) rerenderWidget(pollUiCtx!);
 		}, pollIntervalMs);
 		state.poller.unref?.();
 	};
 
 	const hydrateActiveJobs = (ctx?: ExtensionContext) => {
-		if (ctx?.hasUI) state.lastUiContext = ctx;
-		const renderCtx = state.lastUiContext?.hasUI ? state.lastUiContext : undefined;
-		const currentCwd = (ctx?.cwd ?? state.lastUiContext?.cwd ?? state.baseCwd) || undefined;
+		if (ctxHasUI(ctx)) state.lastUiContext = ctx!;
+		const retainedCtx = liveUiContext();
+		const renderCtx = ctxHasUI(retainedCtx) ? retainedCtx : undefined;
+		const currentCwd = (ctxCwd(ctx) ?? ctxCwd(retainedCtx) ?? state.baseCwd) || undefined;
 		let summaries: AsyncRunSummary[];
 		try {
 			summaries = listAsyncRuns(asyncDirRoot, {
@@ -304,6 +349,7 @@ export function createAsyncJobTracker(pi: Pick<ExtensionAPI, "events">, state: S
 				resultsDir,
 				kill: options.kill,
 				now: options.now,
+				maxAgeMs: ACTIVE_HYDRATION_MAX_AGE_MS,
 			});
 		} catch (error) {
 			console.error(`Failed to hydrate active async jobs from '${asyncDirRoot}':`, error);
@@ -358,8 +404,9 @@ export function createAsyncJobTracker(pi: Pick<ExtensionAPI, "events">, state: S
 			updatedAt: now,
 		});
 		ensurePoller();
-		if (state.lastUiContext) {
-			rerenderWidget(state.lastUiContext);
+		const startedUiCtx = liveUiContext();
+		if (startedUiCtx) {
+			rerenderWidget(startedUiCtx);
 		}
 	};
 
@@ -380,8 +427,9 @@ export function createAsyncJobTracker(pi: Pick<ExtensionAPI, "events">, state: S
 				console.error(`Failed to refresh nested async descendants for '${job.asyncDir}':`, error);
 			}
 		}
-		if (state.lastUiContext) {
-			rerenderWidget(state.lastUiContext);
+		const completeUiCtx = liveUiContext();
+		if (completeUiCtx) {
+			rerenderWidget(completeUiCtx);
 		}
 		if (!nestedRefreshFailed && !hasLiveNestedDescendants(job?.nestedChildren)) scheduleCleanup(asyncId);
 	};
@@ -395,8 +443,22 @@ export function createAsyncJobTracker(pi: Pick<ExtensionAPI, "events">, state: S
 		state.foregroundControls?.clear();
 		state.lastForegroundControlId = null;
 		state.resultFileCoalescer.clear();
-		if (ctx?.hasUI) state.lastUiContext = ctx;
+		if (ctxHasUI(ctx)) state.lastUiContext = ctx!;
+	};
+
+	// Hydration scans the async run root synchronously; deferring it off the
+	// session_start hot path keeps startup latency independent of run history.
+	let pendingDeferredHydration: ReturnType<typeof setTimeout> | null = null;
+	const hydrateActiveJobsDeferred = (ctx?: ExtensionContext) => {
+		if (ctxHasUI(ctx)) state.lastUiContext = ctx!;
+		if (pendingDeferredHydration !== null) clearTimeout(pendingDeferredHydration);
+		const timer = setTimeout(() => {
+			pendingDeferredHydration = null;
+			hydrateActiveJobs(ctx);
+		}, 0);
+		timer.unref?.();
+		pendingDeferredHydration = timer;
 	};
 
-	return { ensurePoller, handleStarted, handleComplete, resetJobs, hydrateActiveJobs };
+	return { ensurePoller, handleStarted, handleComplete, resetJobs, hydrateActiveJobs, hydrateActiveJobsDeferred };
 }

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

@@ -75,6 +75,8 @@ interface AsyncRunListOptions {
 	kill?: (pid: number, signal?: NodeJS.Signals | 0) => boolean;
 	now?: () => number;
 	reconcile?: boolean;
+	/** Only consider run dirs whose dir or status.json changed within this window. */
+	maxAgeMs?: number;
 }
 
 function getErrorMessage(error: unknown): string {
@@ -100,6 +102,19 @@ function isAsyncRunDir(root: string, entry: string): boolean {
 	}
 }
 
+function runDirTouchedSince(asyncDir: string, cutoffMs: number): boolean {
+	try {
+		if (fs.statSync(asyncDir).mtimeMs >= cutoffMs) return true;
+	} catch {
+		return false;
+	}
+	try {
+		return fs.statSync(path.join(asyncDir, "status.json")).mtimeMs >= cutoffMs;
+	} catch {
+		return false;
+	}
+}
+
 function outputFileMtime(outputFile: string | undefined): number | undefined {
 	if (!outputFile) return undefined;
 	try {
@@ -232,9 +247,13 @@ export function listAsyncRuns(asyncDirRoot: string, options: AsyncRunListOptions
 	}
 
 	const allowedStates = options.states ? new Set(options.states) : undefined;
+	const cutoff = options.maxAgeMs !== undefined ? (options.now?.() ?? Date.now()) - options.maxAgeMs : undefined;
 	const runs: AsyncRunSummary[] = [];
 	for (const entry of entries) {
 		const asyncDir = path.join(asyncDirRoot, entry);
+		// Recency cutoff: skip reconcile/read/parse work for long-untouched runs
+		// (two stats instead of a full per-run reconciliation at startup).
+		if (cutoff !== undefined && !runDirTouchedSince(asyncDir, cutoff)) continue;
 		const reconciliation = options.reconcile === false
 			? undefined
 			: reconcileAsyncRun(asyncDir, { resultsDir: options.resultsDir, kill: options.kill, now: options.now });

package/dist/builtin/subagents/src/runs/background/completion-notification.ts

@@ -4,6 +4,7 @@ import { SUBAGENT_ASYNC_COMPLETE_EVENT } from "../../shared/types.ts";
 export interface CompletionNotificationEnvelope extends Record<string, unknown> {
 	notificationId: string;
 	acknowledge: (delivered: boolean) => void;
+	defer: () => void;
 }
 
 export function deliverLocalCompletionNotification(
@@ -13,6 +14,7 @@ export function deliverLocalCompletionNotification(
 ): Promise<boolean> {
 	return new Promise((resolve) => {
 		let settled = false;
+		let deferred = false;
 		const finish = (delivered: boolean) => {
 			if (settled) return;
 			settled = true;
@@ -22,11 +24,10 @@ export function deliverLocalCompletionNotification(
 			events.emit(SUBAGENT_ASYNC_COMPLETE_EVENT, {
 				...payload,
 				notificationId,
+				defer: () => { deferred = true; },
 				acknowledge: finish,
 			} satisfies CompletionNotificationEnvelope);
-			// The established event contract treats successful synchronous emission as
-			// delivery. Production listeners can synchronously reject via acknowledge(false).
-			finish(true);
+			if (!deferred) finish(true);
 		} catch {
 			finish(false);
 		}