pi-subagents 0.34.0 → 0.35.0

package/src/runs/background/control-channel.ts

@@ -19,6 +19,7 @@ import * as fs from "node:fs";
 import * as path from "node:path";
 import { writeAtomicJson } from "../../shared/atomic-json.ts";
 import { POLL_INTERVAL_MS } from "../../shared/types.ts";
+import { resolveWatchPath } from "../../shared/utils.ts";
 
 /**
  * Opportunistic fast-path interrupt signal. On Unix `SIGUSR2` is trapped by the
@@ -27,7 +28,7 @@ import { POLL_INTERVAL_MS } from "../../shared/types.ts";
  */
 export const INTERRUPT_SIGNAL: NodeJS.Signals = process.platform === "win32" ? "SIGBREAK" : "SIGUSR2";
 
-export type ControlChannelFs = Pick<typeof fs, "mkdirSync" | "existsSync" | "rmSync" | "watch" | "readdirSync" | "readFileSync">;
+export type ControlChannelFs = Pick<typeof fs, "mkdirSync" | "existsSync" | "rmSync" | "watch" | "readdirSync" | "readFileSync" | "realpathSync">;
 export type ControlChannelTimers = { setInterval: typeof setInterval; clearInterval: typeof clearInterval };
 type KillFn = (pid: number, signal?: NodeJS.Signals | 0) => unknown;
 
@@ -45,17 +46,49 @@ export interface TimeoutRequest {
 	reason?: string;
 }
 
+export interface StopRequest {
+	type: "stop";
+	ts?: number;
+	source?: string;
+	reason?: string;
+}
+
 export interface SteerRequest {
 	type: "steer";
 	id: string;
 	ts: number;
 	message: string;
 	targetIndex?: number;
+	targetIndexes?: number[];
 	source?: string;
 }
 
+export interface SteerCapability {
+	type: "steer-capability";
+	protocolVersion: 1;
+	index: number;
+	pid: number;
+	readyAt: number;
+	supported: boolean;
+}
+
+export interface SteerAck {
+	type: "steer-ack";
+	protocolVersion: 1;
+	requestId: string;
+	index: number;
+	ts: number;
+	state: "delivered" | "failed";
+	message: string;
+}
+
 const STEER_REQUESTS_DIR = "steer-requests";
 const STEER_TARGETS_DIR = "steer-targets";
+const STEER_CAPABILITIES_DIR = "steer-capabilities";
+const STEER_ACKS_DIR = "steer-acks";
+const STEER_INBOX_CLOSED_FILE = "steer-inbox-closed.json";
+const MAX_STEER_MESSAGE_BYTES = 128 * 1024;
+const MAX_STEER_REQUEST_ID_LENGTH = 256;
 
 /** Control inbox directory inside an async run dir. */
 export function controlInboxDir(asyncDir: string): string {
@@ -72,26 +105,118 @@ export function timeoutRequestPath(asyncDir: string): string {
 	return path.join(controlInboxDir(asyncDir), "timeout.json");
 }
 
+/** Path of the portable manual stop request file. */
+export function stopRequestPath(asyncDir: string): string {
+	return path.join(controlInboxDir(asyncDir), "stop.json");
+}
+
 /** Directory of parent-to-runner steering requests. */
 export function steerRequestsDir(asyncDir: string): string {
 	return path.join(controlInboxDir(asyncDir), STEER_REQUESTS_DIR);
 }
 
+export function steerInboxClosedPath(asyncDir: string): string {
+	return path.join(controlInboxDir(asyncDir), STEER_INBOX_CLOSED_FILE);
+}
+
+export function closeSteerInbox(asyncDir: string, state: string): void {
+	writeAtomicJson(steerInboxClosedPath(asyncDir), { version: 1, closedAt: Date.now(), state });
+}
+
 /** Per-child inbox consumed by the child prompt runtime inside the Pi process. */
 export function stepSteerInboxDir(asyncDir: string, index: number): string {
+	assertChildIndex(index);
 	return path.join(controlInboxDir(asyncDir), STEER_TARGETS_DIR, String(index));
 }
 
+export function steerCapabilitiesDir(asyncDir: string): string {
+	return path.join(controlInboxDir(asyncDir), STEER_CAPABILITIES_DIR);
+}
+
+export function steerCapabilityPath(asyncDir: string, index: number): string {
+	assertChildIndex(index);
+	return path.join(steerCapabilitiesDir(asyncDir), `${index}.json`);
+}
+
+export function steerAcksDir(asyncDir: string, index: number): string {
+	assertChildIndex(index);
+	return path.join(controlInboxDir(asyncDir), STEER_ACKS_DIR, String(index));
+}
+
+function steerAckFileName(requestId: string): string {
+	return `${Buffer.from(requestId).toString("base64url")}.json`;
+}
+
+export function steerAckPathFromDir(dir: string, requestId: string): string {
+	if (!/^[^\s]+$/.test(requestId) || requestId.length > 256) throw new Error("steer acknowledgment requestId is invalid.");
+	return path.join(dir, steerAckFileName(requestId));
+}
+
+function assertChildIndex(index: number): void {
+	if (!Number.isInteger(index) || index < 0 || index > 1_000_000) throw new Error("steer child index must be a non-negative integer.");
+}
+
 function steerRequestFileName(request: SteerRequest): string {
 	return `${String(request.ts).padStart(13, "0")}-${Buffer.from(request.id).toString("base64url")}.json`;
 }
 
+function validSteerRequest(request: Partial<SteerRequest>): request is SteerRequest {
+	return request.type === "steer"
+		&& typeof request.id === "string"
+		&& /^[^\s]+$/.test(request.id)
+		&& request.id.length <= MAX_STEER_REQUEST_ID_LENGTH
+		&& typeof request.ts === "number"
+		&& Number.isFinite(request.ts)
+		&& request.ts > 0
+		&& typeof request.message === "string"
+		&& Boolean(request.message.trim())
+		&& Buffer.byteLength(request.message, "utf8") <= MAX_STEER_MESSAGE_BYTES
+		&& (request.targetIndex === undefined || (Number.isInteger(request.targetIndex) && request.targetIndex >= 0 && request.targetIndex <= 1_000_000))
+		&& (request.targetIndexes === undefined || (
+			request.targetIndex === undefined
+			&& Array.isArray(request.targetIndexes)
+			&& request.targetIndexes.length > 0
+			&& request.targetIndexes.length <= 1_000
+			&& request.targetIndexes.every((index) => Number.isInteger(index) && index >= 0 && index <= 1_000_000)
+			&& new Set(request.targetIndexes).size === request.targetIndexes.length
+		))
+		&& (request.source === undefined || (typeof request.source === "string" && Boolean(request.source.trim()) && request.source.length <= 256));
+}
+
 export function writeSteerRequestToDir(dir: string, request: SteerRequest): string {
+	if (!validSteerRequest(request)) throw new Error("steer request is malformed or exceeds transport limits.");
 	const requestPath = path.join(dir, steerRequestFileName(request));
 	writeAtomicJson(requestPath, request);
 	return requestPath;
 }
 
+export function writeSteerCapabilityAt(filePath: string, capability: Omit<SteerCapability, "type" | "protocolVersion">): string {
+	assertChildIndex(capability.index);
+	if (!Number.isInteger(capability.pid) || capability.pid <= 0) throw new Error("steer capability pid must be a positive integer.");
+	if (!Number.isFinite(capability.readyAt) || capability.readyAt <= 0) throw new Error("steer capability readyAt must be a finite timestamp.");
+	const record: SteerCapability = { type: "steer-capability", protocolVersion: 1, ...capability };
+	writeAtomicJson(filePath, record);
+	return filePath;
+}
+
+export function writeSteerCapability(asyncDir: string, capability: Omit<SteerCapability, "type" | "protocolVersion">): string {
+	return writeSteerCapabilityAt(steerCapabilityPath(asyncDir, capability.index), capability);
+}
+
+export function writeSteerAckAt(filePath: string, ack: Omit<SteerAck, "type" | "protocolVersion">): string {
+	assertChildIndex(ack.index);
+	if (!/^[^\s]+$/.test(ack.requestId) || ack.requestId.length > 256) throw new Error("steer acknowledgment requestId is invalid.");
+	if (!Number.isFinite(ack.ts) || ack.ts <= 0) throw new Error("steer acknowledgment ts must be a finite timestamp.");
+	if (!ack.message.trim() || ack.message.length > 1000) throw new Error("steer acknowledgment message is invalid.");
+	const record: SteerAck = { type: "steer-ack", protocolVersion: 1, ...ack, message: ack.message.trim() };
+	writeAtomicJson(filePath, record);
+	return filePath;
+}
+
+export function writeSteerAck(asyncDir: string, ack: Omit<SteerAck, "type" | "protocolVersion">): string {
+	return writeSteerAckAt(path.join(steerAcksDir(asyncDir, ack.index), steerAckFileName(ack.requestId)), ack);
+}
+
 /**
  * Parent side: drop a portable interrupt request the runner's inbox watcher will
  * pick up regardless of OS. Written atomically (temp + rename), dir auto-created.
@@ -118,46 +243,137 @@ export function requestAsyncTimeout(
 	return requestPath;
 }
 
+export function requestAsyncStop(
+	asyncDir: string,
+	payload: Omit<StopRequest, "type"> = {},
+	deps: { now?: () => number } = {},
+): string {
+	const requestPath = stopRequestPath(asyncDir);
+	const request: StopRequest = { ...payload, ts: payload.ts ?? deps.now?.() ?? Date.now(), type: "stop" };
+	writeAtomicJson(requestPath, request);
+	return requestPath;
+}
+
 export function requestAsyncSteer(
 	asyncDir: string,
-	payload: { message: string; targetIndex?: number; source?: string; id?: string; ts?: number },
+	payload: { message: string; targetIndex?: number; targetIndexes?: number[]; source?: string; id?: string; ts?: number },
 	deps: { now?: () => number; randomId?: () => string } = {},
 ): string {
 	const message = payload.message.trim();
 	if (!message) throw new Error("steer message must not be empty.");
-	if (payload.targetIndex !== undefined && (!Number.isInteger(payload.targetIndex) || payload.targetIndex < 0)) {
-		throw new Error("steer targetIndex must be a non-negative integer.");
+	if (Buffer.byteLength(message, "utf8") > MAX_STEER_MESSAGE_BYTES) throw new Error(`steer message exceeds ${MAX_STEER_MESSAGE_BYTES} UTF-8 bytes.`);
+	if (payload.targetIndex !== undefined && (!Number.isInteger(payload.targetIndex) || payload.targetIndex < 0 || payload.targetIndex > 1_000_000)) {
+		throw new Error("steer targetIndex must be an integer between 0 and 1000000.");
 	}
+	if (payload.targetIndexes !== undefined && (
+		!Array.isArray(payload.targetIndexes)
+		|| payload.targetIndex !== undefined
+		|| payload.targetIndexes.length === 0
+		|| payload.targetIndexes.length > 1_000
+		|| payload.targetIndexes.some((index) => !Number.isInteger(index) || index < 0 || index > 1_000_000)
+		|| new Set(payload.targetIndexes).size !== payload.targetIndexes.length
+	)) {
+		throw new Error("steer targetIndexes must contain 1-1000 unique non-negative integers and cannot be combined with targetIndex.");
+	}
+	const closedPath = steerInboxClosedPath(asyncDir);
+	if (fs.existsSync(closedPath)) throw new Error("Async run no longer accepts steering requests.");
 	const request: SteerRequest = {
 		type: "steer",
 		id: payload.id ?? deps.randomId?.() ?? randomUUID(),
 		ts: payload.ts ?? deps.now?.() ?? Date.now(),
 		message,
 		...(payload.targetIndex !== undefined ? { targetIndex: payload.targetIndex } : {}),
+		...(payload.targetIndexes !== undefined ? { targetIndexes: [...payload.targetIndexes] } : {}),
 		...(payload.source ? { source: payload.source } : {}),
 	};
-	return writeSteerRequestToDir(steerRequestsDir(asyncDir), request);
+	const requestPath = writeSteerRequestToDir(steerRequestsDir(asyncDir), request);
+	if (fs.existsSync(closedPath)) {
+		fs.rmSync(requestPath, { force: true });
+		throw new Error("Async run stopped accepting steering before the request was committed.");
+	}
+	return requestPath;
 }
 
 export function enqueueStepSteer(asyncDir: string, index: number, request: SteerRequest): string {
-	if (!Number.isInteger(index) || index < 0) throw new Error("steer child index must be a non-negative integer.");
-	return writeSteerRequestToDir(stepSteerInboxDir(asyncDir, index), { ...request, targetIndex: index, type: "steer" });
+	assertChildIndex(index);
+	const { targetIndexes: _targetIndexes, ...singleTargetRequest } = request;
+	return writeSteerRequestToDir(stepSteerInboxDir(asyncDir, index), { ...singleTargetRequest, targetIndex: index, type: "steer" });
+}
+
+function parseSteerCapability(raw: unknown): SteerCapability | undefined {
+	if (!raw || typeof raw !== "object" || Array.isArray(raw)) return undefined;
+	const input = raw as Partial<SteerCapability>;
+	if (input.type !== "steer-capability" || input.protocolVersion !== 1) return undefined;
+	if (!Number.isInteger(input.index) || input.index < 0 || input.index > 1_000_000) return undefined;
+	if (!Number.isInteger(input.pid) || input.pid <= 0 || !Number.isFinite(input.readyAt) || input.readyAt <= 0 || typeof input.supported !== "boolean") return undefined;
+	return { type: "steer-capability", protocolVersion: 1, index: input.index, pid: input.pid, readyAt: input.readyAt, supported: input.supported };
+}
+
+function parseSteerAck(raw: unknown): SteerAck | undefined {
+	if (!raw || typeof raw !== "object" || Array.isArray(raw)) return undefined;
+	const input = raw as Partial<SteerAck>;
+	if (input.type !== "steer-ack" || input.protocolVersion !== 1 || typeof input.requestId !== "string" || !/^[^\s]+$/.test(input.requestId) || input.requestId.length > 256) return undefined;
+	if (!Number.isInteger(input.index) || input.index < 0 || input.index > 1_000_000 || !Number.isFinite(input.ts) || input.ts <= 0) return undefined;
+	if (input.state !== "delivered" && input.state !== "failed") return undefined;
+	if (typeof input.message !== "string" || !input.message.trim() || input.message.length > 1000) return undefined;
+	return { type: "steer-ack", protocolVersion: 1, requestId: input.requestId, index: input.index, ts: input.ts, state: input.state, message: input.message.trim() };
+}
+
+export function readSteerCapability(asyncDir: string, index: number): SteerCapability | undefined {
+	try {
+		return parseSteerCapability(JSON.parse(fs.readFileSync(steerCapabilityPath(asyncDir, index), "utf-8")));
+	} catch {
+		return undefined;
+	}
+}
+
+export function consumeSteerCapabilities(asyncDir: string, fsImpl: Pick<typeof fs, "existsSync" | "readdirSync" | "readFileSync"> = fs): SteerCapability[] {
+	const dir = steerCapabilitiesDir(asyncDir);
+	if (!fsImpl.existsSync(dir)) return [];
+	const capabilities: SteerCapability[] = [];
+	for (const entry of fsImpl.readdirSync(dir).filter((name) => /^\d+\.json$/.test(name)).sort()) {
+		try {
+			const capability = parseSteerCapability(JSON.parse(fsImpl.readFileSync(path.join(dir, entry), "utf-8")));
+			if (capability) capabilities.push(capability);
+		} catch {
+			// A partially written or malformed capability is ignored until a valid one arrives.
+		}
+	}
+	return capabilities;
+}
+
+export function consumeSteerAcks(asyncDir: string, fsImpl: Pick<typeof fs, "existsSync" | "readdirSync" | "readFileSync" | "rmSync"> = fs): SteerAck[] {
+	const root = path.join(controlInboxDir(asyncDir), STEER_ACKS_DIR);
+	if (!fsImpl.existsSync(root)) return [];
+	const acks: SteerAck[] = [];
+	let indexNames: string[];
+	try { indexNames = fsImpl.readdirSync(root).filter((name) => /^\d+$/.test(name)); } catch { return []; }
+	for (const indexName of indexNames) {
+		const dir = path.join(root, indexName);
+		let entries: string[];
+		try { entries = fsImpl.readdirSync(dir).filter((name) => name.endsWith(".json")).sort(); } catch { continue; }
+		for (const entry of entries) {
+			const target = path.join(dir, entry);
+			let ack: SteerAck | undefined;
+			try { ack = parseSteerAck(JSON.parse(fsImpl.readFileSync(target, "utf-8"))); } catch { ack = undefined; }
+			try { fsImpl.rmSync(target, { force: true }); } catch { continue; }
+			if (ack) acks.push(ack);
+		}
+	}
+	return acks;
 }
 
 function parseSteerRequest(raw: unknown): SteerRequest | undefined {
 	if (!raw || typeof raw !== "object" || Array.isArray(raw)) return undefined;
 	const input = raw as Partial<SteerRequest>;
-	if (input.type !== "steer") return undefined;
-	if (typeof input.id !== "string" || !input.id.trim()) return undefined;
-	if (typeof input.ts !== "number" || !Number.isFinite(input.ts)) return undefined;
-	if (typeof input.message !== "string" || !input.message.trim()) return undefined;
-	if (input.targetIndex !== undefined && (!Number.isInteger(input.targetIndex) || input.targetIndex < 0)) return undefined;
+	if (!validSteerRequest(input)) return undefined;
 	return {
 		type: "steer",
 		id: input.id.trim(),
 		ts: input.ts,
 		message: input.message.trim(),
 		...(input.targetIndex !== undefined ? { targetIndex: input.targetIndex } : {}),
+		...(input.targetIndexes !== undefined ? { targetIndexes: [...input.targetIndexes] } : {}),
 		...(typeof input.source === "string" && input.source.trim() ? { source: input.source } : {}),
 	};
 }
@@ -220,6 +436,20 @@ export function consumeTimeoutRequest(
 	return true;
 }
 
+export function consumeStopRequest(
+	asyncDir: string,
+	fsImpl: Pick<typeof fs, "existsSync" | "rmSync"> = fs,
+): boolean {
+	const requestPath = stopRequestPath(asyncDir);
+	if (!fsImpl.existsSync(requestPath)) return false;
+	try {
+		fsImpl.rmSync(requestPath, { force: true, recursive: true });
+	} catch {
+		// Already removed by a concurrent check — still counts as consumed.
+	}
+	return true;
+}
+
 /**
  * Parent side: portable interrupt = authoritative file request + best-effort OS
  * signal. The signal is only a latency optimization on Unix; ENOSYS on Windows
@@ -265,6 +495,17 @@ export function deliverTimeoutRequest(input: {
 	requestAsyncTimeout(input.asyncDir, input.source ? { source: input.source } : {}, { now: input.now });
 }
 
+export function deliverStopRequest(input: {
+	asyncDir: string;
+	pid?: number;
+	kill?: KillFn;
+	signal?: NodeJS.Signals;
+	now?: () => number;
+	source?: string;
+}): void {
+	requestAsyncStop(input.asyncDir, input.source ? { source: input.source } : {}, { now: input.now });
+}
+
 /**
  * Runner side: watch the control inbox and route interrupt requests into
  * `onInterrupt`. Uses `fs.watch` when available plus an interval poll as a
@@ -276,7 +517,10 @@ export function watchAsyncControlInbox(
 	opts: {
 		onInterrupt: () => void;
 		onTimeout?: () => void;
+		onStop?: () => void;
 		onSteer?: (request: SteerRequest) => void;
+		onSteerCapability?: (capability: SteerCapability) => void;
+		onSteerAck?: (ack: SteerAck) => void;
 		pollIntervalMs?: number;
 		fs?: ControlChannelFs;
 		timers?: ControlChannelTimers;
@@ -295,9 +539,12 @@ export function watchAsyncControlInbox(
 	const check = (): void => {
 		if (disposed) return;
 		try {
+			if (consumeStopRequest(asyncDir, fsImpl)) opts.onStop?.();
 			if (consumeTimeoutRequest(asyncDir, fsImpl)) opts.onTimeout?.();
 			if (consumeInterruptRequest(asyncDir, fsImpl)) opts.onInterrupt();
 			for (const request of consumeSteerRequests(asyncDir, fsImpl)) opts.onSteer?.(request);
+			for (const capability of consumeSteerCapabilities(asyncDir, fsImpl)) opts.onSteerCapability?.(capability);
+			for (const ack of consumeSteerAcks(asyncDir, fsImpl)) opts.onSteerAck?.(ack);
 		} catch {
 			// Never let inbox errors crash the runner.
 		}
@@ -308,7 +555,7 @@ export function watchAsyncControlInbox(
 
 	let watcher: fs.FSWatcher | undefined;
 	try {
-		watcher = fsImpl.watch(dir, () => check());
+		watcher = fsImpl.watch(resolveWatchPath(dir, fsImpl.realpathSync.native), () => check());
 		watcher.on?.("error", () => {
 			// fs.watch can emit on transient FS errors; the interval poll keeps us live.
 		});

package/src/runs/background/fleet-view.ts

@@ -23,6 +23,7 @@ const MAX_TRANSCRIPT_LINES = 500;
 const TRANSCRIPT_TAIL_BYTES = 256 * 1024;
 
 type ForegroundControl = SubagentState["foregroundControls"] extends Map<string, infer T> ? T : never;
+type ForegroundRun = NonNullable<SubagentState["foregroundRuns"]> extends Map<string, infer T> ? T : never;
 
 interface FleetViewParams {
 	lines?: number;
@@ -254,6 +255,20 @@ function formatForegroundFleetLines(controls: ForegroundControl[]): string[] {
 	return lines;
 }
 
+function formatDetachedForegroundFleetLines(runs: ForegroundRun[]): string[] {
+	if (runs.length === 0) return [];
+	const lines = ["Detached foreground runs:"];
+	const ordered = [...runs].sort((left, right) => right.updatedAt - left.updatedAt);
+	for (const run of ordered) {
+		const detachedChildren = run.children.filter((child) => child.status === "detached");
+		const childSummary = detachedChildren.map((child) => `${child.agent} #${child.index}`).join(", ");
+		lines.push(`- ${run.runId} | detached | ${run.mode}${childSummary ? ` | ${childSummary}` : ""}`);
+		lines.push(`  status: subagent({ action: "status", id: "${run.runId}" })`);
+		lines.push(`  recovery: reply to the supervisor request first, then wait with subagent_wait({ id: "${run.runId}" }); do not resume or launch a replacement while any child remains detached.`);
+	}
+	return lines;
+}
+
 function formatAsyncFleetLines(runs: AsyncRunSummary[]): string[] {
 	if (runs.length === 0) return [];
 	const lines = ["Async runs:"];
@@ -316,7 +331,11 @@ export function inspectSubagentFleet(_params: FleetViewParams, deps: FleetViewDe
 	}
 
 	const foregroundControls = deps.state ? [...deps.state.foregroundControls.values()] : [];
-	const total = foregroundControls.length + asyncRuns.length;
+	const activeForegroundIds = new Set(foregroundControls.map((control) => control.runId));
+	const detachedForegroundRuns = deps.state?.foregroundRuns
+		? [...deps.state.foregroundRuns.values()].filter((run) => run.sessionId === deps.state?.currentSessionId && !activeForegroundIds.has(run.runId) && run.children.some((child) => child.status === "detached"))
+		: [];
+	const total = foregroundControls.length + detachedForegroundRuns.length + asyncRuns.length;
 	if (total === 0) {
 		return {
 			content: [{ type: "text", text: "No active subagent fleet. Background runs that already finished are available through completion notifications or subagent({ action: \"status\", id: \"...\" })." }],
@@ -324,9 +343,11 @@ export function inspectSubagentFleet(_params: FleetViewParams, deps: FleetViewDe
 		};
 	}
 
-	const lines = [`Subagent fleet: ${total} active`, ""];
+	const lines = [`Subagent fleet: ${total} tracked`, ""];
 	const foregroundLines = formatForegroundFleetLines(foregroundControls);
 	if (foregroundLines.length) lines.push(...foregroundLines, "");
+	const detachedForegroundLines = formatDetachedForegroundFleetLines(detachedForegroundRuns);
+	if (detachedForegroundLines.length) lines.push(...detachedForegroundLines, "");
 	const asyncLines = formatAsyncFleetLines(asyncRuns);
 	if (asyncLines.length) lines.push(...asyncLines, "");
 	lines.push("Commands:");

package/src/runs/background/notify.ts

@@ -16,7 +16,7 @@ import {
 	createCompletionBatcher,
 	resolveCompletionBatchConfig,
 } from "./completion-batcher.ts";
-import { SUBAGENT_ASYNC_COMPLETE_EVENT, type SubagentState } from "../../shared/types.ts";
+import { SUBAGENT_ASYNC_COMPLETE_EVENT, SUBAGENT_FOREGROUND_COMPLETE_EVENT, type SubagentState } from "../../shared/types.ts";
 
 interface ChainStepResult {
 	agent: string;
@@ -27,6 +27,7 @@ interface ChainStepResult {
 export interface SubagentNotifyDetails {
 	agent: string;
 	status: "completed" | "failed" | "paused";
+	source?: "async" | "foreground";
 	taskInfo?: string;
 	resultPreview: string;
 	durationMs?: number;
@@ -36,6 +37,7 @@ export interface SubagentNotifyDetails {
 
 interface SubagentResult {
 	id: string | null;
+	source?: "async" | "foreground";
 	agent: string | null;
 	success: boolean;
 	summary: string;
@@ -72,8 +74,9 @@ function formatSessionLine(details: SubagentNotifyDetails): string | undefined {
 
 export function formatSingleCompletion(details: SubagentNotifyDetails): string {
 	const sessionLine = formatSessionLine(details);
+	const taskKind = details.source === "foreground" ? "Detached foreground task" : "Background task";
 	return [
-		`Background task ${details.status}: **${details.agent}**${details.taskInfo ?? ""}`,
+		`${taskKind} ${details.status}: **${details.agent}**${details.taskInfo ?? ""}`,
 		"",
 		details.resultPreview.trim() ? details.resultPreview : "(no output)",
 		sessionLine ? "" : undefined,
@@ -83,6 +86,37 @@ export function formatSingleCompletion(details: SubagentNotifyDetails): string {
 		.join("\n");
 }
 
+export function parseSubagentNotifyContent(content: string): SubagentNotifyDetails | undefined {
+	const lines = content.split("\n");
+	const match = (lines[0] ?? "").match(/^(Background task|Detached foreground 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;
+		}
+	}
+	const sessionLine = sessionIndex >= 0 ? body[sessionIndex] : undefined;
+	const resultPreview = (sessionIndex >= 0 ? body.slice(0, sessionIndex) : body).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 {
+		agent: match[3]!,
+		status: match[2] as SubagentNotifyDetails["status"],
+		...(match[1] === "Detached foreground task" ? { source: "foreground" as const } : {}),
+		...(match[4] ? { taskInfo: match[4] } : {}),
+		resultPreview,
+		...(sessionLabel && sessionValue ? { sessionLabel, sessionValue } : {}),
+	};
+}
+
 export function formatGroupedCompletion(details: SubagentNotifyDetails[]): string {
 	const header = `Background tasks completed (${details.length}): ${details.map((d) => `**${d.agent}**${d.taskInfo ?? ""}`).join(", ")}`;
 	const blocks: string[] = [header, ""];
@@ -147,6 +181,7 @@ export function buildCompletionDetails(result: SubagentResult): SubagentNotifyDe
 	return {
 		agent,
 		status,
+		...(result.source ? { source: result.source } : {}),
 		...(taskInfo ? { taskInfo } : {}),
 		resultPreview: summary,
 		...(typeof result.durationMs === "number" ? { durationMs: result.durationMs } : {}),
@@ -158,7 +193,7 @@ export default function registerSubagentNotify(
 	pi: ExtensionAPI,
 	state: Pick<SubagentState, "currentSessionId">,
 	options: RegisterSubagentNotifyOptions = {},
-): void {
+): () => void {
 	const unsubscribeStoreKey = "__pi_subagents_notify_unsubscribe__";
 	const batcherStoreKey = "__pi_subagents_notify_batcher__";
 	const globalStore = globalThis as Record<string, unknown>;
@@ -184,14 +219,10 @@ export default function registerSubagentNotify(
 	const nowFn = options.now ?? Date.now;
 	const batchConfig = resolveCompletionBatchConfig(options.batchConfig);
 	const batchers = new Map<string, CompletionBatcher<SubagentNotifyDetails>>();
-	globalStore[batcherStoreKey] = {
-		dispose() {
-			for (const batcher of batchers.values()) batcher.dispose();
-			batchers.clear();
-		},
-	};
+	let disposed = false;
 
 	const handleComplete = (data: unknown) => {
+		if (disposed) return;
 		const result = data as SubagentResult;
 		if (typeof result.sessionId !== "string" || result.sessionId !== state.currentSessionId) return;
 		const now = nowFn();
@@ -199,6 +230,10 @@ export default function registerSubagentNotify(
 		if (markSeenWithTtl(seen, key, now, ttlMs)) return;
 
 		const details = buildCompletionDetails(result);
+		if (result.source === "foreground") {
+			sendCompletion(pi, [details]);
+			return;
+		}
 		const batchKey = completionBatchKey(result);
 		let batcher = batchers.get(batchKey);
 		if (!batcher) {
@@ -221,5 +256,39 @@ export default function registerSubagentNotify(
 		batcher.push(details);
 	};
 
-	globalStore[unsubscribeStoreKey] = pi.events.on(SUBAGENT_ASYNC_COMPLETE_EVENT, handleComplete);
+	const unsubscribers = [
+		pi.events.on(SUBAGENT_ASYNC_COMPLETE_EVENT, handleComplete),
+		pi.events.on(SUBAGENT_FOREGROUND_COMPLETE_EVENT, handleComplete),
+	].filter((unsubscribe): unsubscribe is () => void => typeof unsubscribe === "function");
+	const batcherRegistration = { dispose };
+
+	function dispose(): void {
+		if (disposed) return;
+		disposed = true;
+		for (const batcher of batchers.values()) {
+			try {
+				batcher.dispose();
+			} catch {
+				// Best effort cleanup must continue through every owned batcher.
+			}
+		}
+		batchers.clear();
+		for (const unsubscribe of unsubscribers) {
+			try {
+				unsubscribe();
+			} catch {
+				// Best effort cleanup must continue through every owned handler.
+			}
+		}
+		if (globalStore[unsubscribeStoreKey] === dispose) {
+			delete globalStore[unsubscribeStoreKey];
+		}
+		if (globalStore[batcherStoreKey] === batcherRegistration) {
+			delete globalStore[batcherStoreKey];
+		}
+	}
+
+	globalStore[unsubscribeStoreKey] = dispose;
+	globalStore[batcherStoreKey] = batcherRegistration;
+	return dispose;
 }

package/src/runs/background/result-watcher.ts

@@ -17,6 +17,7 @@ import {
 	resolveSubagentResultStatus,
 } from "../../intercom/result-intercom.ts";
 import { projectNestedRegistryForRoot, sanitizeSummary } from "../shared/nested-events.ts";
+import { resolveWatchPath } from "../../shared/utils.ts";
 
 const WATCHER_RESTART_DELAY_MS = 3000;
 const POLL_INTERVAL_MS = 3000;
@@ -40,6 +41,8 @@ type ResultFileChild = {
 	output?: string;
 	error?: string;
 	success?: boolean;
+	state?: string;
+	stopped?: boolean;
 	sessionFile?: string;
 	artifactPaths?: { outputPath?: string };
 	intercomTarget?: string;
@@ -91,13 +94,6 @@ function shouldFallBackToPolling(error: unknown): boolean {
 	return code === "EMFILE" || code === "ENOSPC";
 }
 
-function resolveNativeWatchDir(fsApi: ResultWatcherFs, resultsDir: string): string {
-	try {
-		return fsApi.realpathSync.native(resultsDir);
-	} catch {
-		return resultsDir;
-	}
-}
 
 export function createResultWatcher(
 	pi: { events: IntercomEventBus },
@@ -155,11 +151,18 @@ export function createResultWatcher(
 					: output;
 				const sessionPath = result.sessionFile ?? (resultChildren.length === 1 ? data.sessionFile : undefined);
 				const childNestedChildren = sanitizeNestedResultChildren(result.children, resultPath, `results[${index}].children`);
+				const childState = result.state === "paused" || result.state === "stopped"
+					? result.state
+					: result.stopped === true
+						? "stopped"
+						: data.state === "paused" || (!hasResultChildren && (data.state === "stopped" || typeof result.success !== "boolean"))
+							? data.state
+							: undefined;
 				return {
 					agent: result.agent ?? data.agent ?? `step-${index + 1}`,
 					status: resolveSubagentResultStatus({
 						success: result.success,
-						state: data.state === "paused" || typeof result.success !== "boolean" ? data.state : undefined,
+						state: childState,
 					}),
 					summary,
 					index,
@@ -271,7 +274,7 @@ export function createResultWatcher(
 			state.watcherRestartTimer = null;
 		}
 		try {
-			const watchDir = resolveNativeWatchDir(fsApi, resultsDir);
+			const watchDir = resolveWatchPath(resultsDir, fsApi.realpathSync.native);
 			state.watcher = fsApi.watch(watchDir, (ev, file) => {
 				if (ev !== "rename" || !file) return;
 				const fileName = file.toString();