pi-subagents 0.30.0 → 0.31.1

package/src/runs/background/async-execution.ts

@@ -11,7 +11,7 @@ import { createRequire } from "node:module";
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import type { AgentConfig } from "../../agents/agents.ts";
 import { applyThinkingSuffix } from "../shared/pi-args.ts";
-import { injectSingleOutputInstruction, normalizeSingleOutputOverride, resolveSingleOutputPath, validateFileOnlyOutputMode } from "../shared/single-output.ts";
+import { injectOutputPathSystemPrompt, injectSingleOutputInstruction, normalizeSingleOutputOverride, resolveSingleOutputPath, validateFileOnlyOutputMode } from "../shared/single-output.ts";
 import { buildChainInstructions, isDynamicParallelStep, isParallelStep, resolveStepBehavior, suppressProgressForReadOnlyTask, writeInitialProgressFile, type ChainStep, type ResolvedStepBehavior, type SequentialStep, type StepOverrides } from "../../shared/settings.ts";
 import type { RunnerStep } from "../shared/parallel-utils.ts";
 import { resolvePiPackageRoot } from "../shared/pi-spawn.ts";
@@ -95,6 +95,8 @@ interface AsyncExecutionContext {
 	pi: ExtensionAPI;
 	cwd: string;
 	currentSessionId: string;
+	/** Parent session id used by permission-system ask forwarding. */
+	parentSessionId?: string;
 	currentModelProvider?: string;
 	currentModel?: ParentModel;
 }
@@ -115,6 +117,7 @@ interface AsyncChainParams {
 	sessionRoot?: string;
 	chainSkills?: string[];
 	sessionFilesByFlatIndex?: (string | undefined)[];
+	progressDir?: string;
 	dynamicFanoutMaxItems?: number;
 	maxSubagentDepth: number;
 	worktreeSetupHook?: string;
@@ -170,6 +173,7 @@ export interface AsyncRunnerStepBuildParams {
 	cwd?: string;
 	chainSkills?: string[];
 	sessionFilesByFlatIndex?: (string | undefined)[];
+	progressDir?: string;
 	dynamicFanoutMaxItems?: number;
 	maxSubagentDepth: number;
 	asyncDir: string;
@@ -277,6 +281,7 @@ export function buildAsyncRunnerSteps(id: string, params: AsyncRunnerStepBuildPa
 	const chainSkills = params.chainSkills ?? [];
 	const availableModels = params.availableModels;
 	const runnerCwd = resolveChildCwd(ctx.cwd, cwd);
+	const progressDir = params.progressDir ?? runnerCwd;
 	const graphChain: ChainStep[] = params.attachRoot
 		? [{
 				agent: params.attachRoot.agent,
@@ -346,8 +351,9 @@ export function buildAsyncRunnerSteps(id: string, params: AsyncRunnerStepBuildPa
 		const readInstructions = buildChainInstructions({ ...behavior, output: false, progress: false }, instructionCwd, false);
 		const isFirstProgressAgent = behavior.progress && !progressPrecreated && !progressInstructionCreated;
 		if (behavior.progress) progressInstructionCreated = true;
-		const progressInstructions = buildChainInstructions({ ...behavior, output: false, reads: false }, runnerCwd, isFirstProgressAgent);
+		const progressInstructions = buildChainInstructions({ ...behavior, output: false, reads: false }, progressDir, isFirstProgressAgent);
 		const outputPath = resolveSingleOutputPath(behavior.output, ctx.cwd, instructionCwd);
+		systemPrompt = injectOutputPathSystemPrompt(systemPrompt, outputPath);
 		const validationError = validateFileOnlyOutputMode(behavior.outputMode, outputPath, `Async step (${s.agent})`);
 		if (validationError) throw new AsyncStartValidationError(validationError);
 		let taskTemplate = s.task ?? "{previous}";
@@ -359,6 +365,7 @@ export function buildAsyncRunnerSteps(id: string, params: AsyncRunnerStepBuildPa
 		const primaryModel = resolveSubagentModelOverride(requestedModel, ctx.currentModel, availableModels, ctx.currentModelProvider);
 		const model = applyThinkingSuffix(primaryModel, a.thinking);
 		return {
+			parentSessionId: ctx.parentSessionId ?? ctx.currentSessionId,
 			agent: s.agent,
 			task,
 			phase: s.phase,
@@ -414,7 +421,7 @@ export function buildAsyncRunnerSteps(id: string, params: AsyncRunnerStepBuildPa
 				});
 				const progressPrecreated = parallelBehaviors.some((behavior) => behavior.progress);
 				if (progressPrecreated) {
-					if (!s.worktree) writeInitialProgressFile(runnerCwd);
+					if (!s.worktree || params.progressDir) writeInitialProgressFile(progressDir);
 					progressInstructionCreated = true;
 				}
 				return {
@@ -439,7 +446,7 @@ export function buildAsyncRunnerSteps(id: string, params: AsyncRunnerStepBuildPa
 				const behavior = suppressProgressForReadOnlyTask(resolveStepBehavior(agent, buildStepOverrides(s.parallel), chainSkills), s.parallel.task, originalTask);
 				const progressPrecreated = behavior.progress;
 				if (progressPrecreated) {
-					writeInitialProgressFile(runnerCwd);
+					writeInitialProgressFile(progressDir);
 					progressInstructionCreated = true;
 				}
 				return {
@@ -539,6 +546,7 @@ export function executeAsyncChain(
 		cwd,
 		chainSkills: params.chainSkills,
 		sessionFilesByFlatIndex,
+		progressDir: params.progressDir ?? (resultMode === "parallel" ? path.join(asyncDir, "progress") : undefined),
 		dynamicFanoutMaxItems: params.dynamicFanoutMaxItems,
 		maxSubagentDepth,
 		asyncDir,
@@ -765,6 +773,7 @@ export function executeAsyncSingle(
 
 	const effectiveOutput = normalizeSingleOutputOverride(params.output, agentConfig.output);
 	const outputPath = resolveSingleOutputPath(effectiveOutput, ctx.cwd, runnerCwd);
+	systemPrompt = injectOutputPathSystemPrompt(systemPrompt, outputPath);
 	const outputMode = params.outputMode ?? "inline";
 	const validationError = validateFileOnlyOutputMode(outputMode, outputPath, `Async single run (${agent})`);
 	if (validationError) return formatAsyncStartError("single", validationError);
@@ -783,6 +792,7 @@ export function executeAsyncSingle(
 				id,
 				steps: [
 					{
+						parentSessionId: ctx.parentSessionId ?? ctx.currentSessionId,
 						agent,
 						task: taskWithOutputInstruction,
 						cwd: runnerCwd,

package/src/runs/background/async-job-tracker.ts

@@ -26,6 +26,10 @@ interface AsyncJobTrackerOptions {
 	now?: () => number;
 }
 
+const CONTROL_EVENT_READ_CHUNK_BYTES = 64 * 1024;
+const MAX_CONTROL_EVENT_LINE_BYTES = 1024 * 1024;
+const CONTROL_EVENT_SCAN_WINDOW_BYTES = 2 * 1024 * 1024;
+
 export function createAsyncJobTracker(pi: Pick<ExtensionAPI, "events">, state: SubagentState, asyncDirRoot: string, options: AsyncJobTrackerOptions = {}): {
 	ensurePoller: () => void;
 	handleStarted: (data: unknown) => void;
@@ -68,25 +72,24 @@ export function createAsyncJobTracker(pi: Pick<ExtensionAPI, "events">, state: S
 		}
 		try {
 			const stat = fs.fstatSync(fd);
-			const cursor = stat.size < (job.controlEventCursor ?? 0) ? 0 : (job.controlEventCursor ?? 0);
+			const savedCursor = job.controlEventCursor;
+			let cursor = stat.size < (savedCursor ?? 0) ? 0 : (savedCursor ?? 0);
+			const startedFromTail = savedCursor === undefined && stat.size > CONTROL_EVENT_SCAN_WINDOW_BYTES;
+			if (startedFromTail) cursor = stat.size - CONTROL_EVENT_SCAN_WINDOW_BYTES;
 			if (stat.size <= cursor) return;
-			const buffer = Buffer.alloc(stat.size - cursor);
-			fs.readSync(fd, buffer, 0, buffer.length, cursor);
-			const lastNewline = buffer.lastIndexOf(0x0a);
-			if (lastNewline === -1) return;
-			job.controlEventCursor = cursor + lastNewline + 1;
-			for (const line of buffer.subarray(0, lastNewline).toString("utf-8").split("\n")) {
-				if (!line.trim()) continue;
+			const scanEnd = Math.min(stat.size, cursor + CONTROL_EVENT_SCAN_WINDOW_BYTES);
+			const handleLine = (line: string) => {
+				if (!line.trim()) return;
 				let parsed: unknown;
 				try {
 					parsed = JSON.parse(line);
 				} catch (error) {
 					console.error(`Ignoring malformed async control event in '${eventsPath}':`, error);
-					continue;
+					return;
 				}
-				if (!parsed || typeof parsed !== "object" || (parsed as { type?: unknown }).type !== "subagent.control") continue;
+				if (!parsed || typeof parsed !== "object" || (parsed as { type?: unknown }).type !== "subagent.control") return;
 				const record = parsed as { event?: ControlEvent; channels?: string[]; childIntercomTarget?: string; noticeText?: string; intercom?: { to?: string; message?: string } };
-				if (!record.event || !Array.isArray(record.channels)) continue;
+				if (!record.event || !Array.isArray(record.channels)) return;
 				const payload = {
 					event: record.event,
 					source: "async" as const,
@@ -104,7 +107,48 @@ export function createAsyncJobTracker(pi: Pick<ExtensionAPI, "events">, state: S
 						message: record.intercom.message,
 					});
 				}
+			};
+			let readCursor = cursor;
+			let lastCompleteCursor = cursor;
+			let lineParts: Buffer[] = [];
+			let lineBytes = 0;
+			let skippingOversizedLine = startedFromTail;
+			const appendLineSegment = (segment: Buffer) => {
+				if (segment.length === 0 || skippingOversizedLine) return;
+				if (lineBytes + segment.length > MAX_CONTROL_EVENT_LINE_BYTES) {
+					lineParts = [];
+					lineBytes = 0;
+					skippingOversizedLine = true;
+					return;
+				}
+				lineParts.push(segment);
+				lineBytes += segment.length;
+			};
+			while (readCursor < scanEnd) {
+				const toRead = Math.min(CONTROL_EVENT_READ_CHUNK_BYTES, scanEnd - readCursor);
+				const buffer = Buffer.alloc(toRead);
+				const bytesRead = fs.readSync(fd, buffer, 0, toRead, readCursor);
+				if (bytesRead <= 0) break;
+				const chunk = bytesRead === buffer.length ? buffer : buffer.subarray(0, bytesRead);
+				let lineStart = 0;
+				for (let index = 0; index < chunk.length; index++) {
+					if (chunk[index] !== 0x0a) continue;
+					appendLineSegment(chunk.subarray(lineStart, index));
+					if (!skippingOversizedLine && lineBytes > 0) {
+						handleLine(Buffer.concat(lineParts, lineBytes).toString("utf-8"));
+					}
+					lineParts = [];
+					lineBytes = 0;
+					skippingOversizedLine = false;
+					lastCompleteCursor = readCursor + index + 1;
+					lineStart = index + 1;
+				}
+				appendLineSegment(chunk.subarray(lineStart));
+				readCursor += bytesRead;
+				if (skippingOversizedLine) job.controlEventCursor = readCursor;
 			}
+			if (lastCompleteCursor > cursor) job.controlEventCursor = lastCompleteCursor;
+			else if (scanEnd < stat.size || startedFromTail) job.controlEventCursor = scanEnd;
 		} catch (error) {
 			console.error(`Failed to read async control events for '${job.asyncDir}':`, error);
 		} finally {
@@ -261,6 +305,7 @@ export function createAsyncJobTracker(pi: Pick<ExtensionAPI, "events">, state: S
 			activeParallelGroup: Boolean(firstGroupCount && firstGroupCount > 0),
 			startedAt: now,
 			updatedAt: now,
+			controlEventCursor: 0,
 		});
 		ensurePoller();
 		if (state.lastUiContext) {

package/src/runs/background/async-resume.ts

@@ -2,6 +2,7 @@ import * as fs from "node:fs";
 import * as path from "node:path";
 import { ASYNC_DIR, RESULTS_DIR, type AsyncStatus, type SubagentState } from "../../shared/types.ts";
 import { resolveSubagentIntercomTarget } from "../../intercom/intercom-bridge.ts";
+import { deliverInterruptRequest } from "./control-channel.ts";
 import { reconcileAsyncRun } from "./stale-run-reconciler.ts";
 
 export const ASYNC_RESUME_INTERRUPT_SIGNAL: NodeJS.Signals = process.platform === "win32" ? "SIGBREAK" : "SIGUSR2";
@@ -38,33 +39,30 @@ export type AsyncResumeTarget = {
 
 type KillFn = (pid: number, signal?: NodeJS.Signals | 0) => boolean;
 
-function readAsyncStatus(asyncDir: string): AsyncStatus | null {
-	const statusPath = path.join(asyncDir, "status.json");
-	try {
-		return JSON.parse(fs.readFileSync(statusPath, "utf-8")) as AsyncStatus;
-	} catch (error) {
-		const code = error && typeof error === "object" && "code" in error ? (error as NodeJS.ErrnoException).code : undefined;
-		if (code === "ENOENT") return null;
-		throw error;
-	}
-}
-
 export function interruptLiveAsyncResumeTarget(input: {
 	target: AsyncResumeTarget & { kind: "live" };
 	state?: Pick<SubagentState, "asyncJobs">;
 	kill?: KillFn;
 	now?: () => number;
+	resultsDir?: string;
 }): { ok: true; asyncId: string } | { ok: false; message: string } {
 	const asyncId = input.target.runId;
 	if (!input.target.asyncDir) {
 		return { ok: false, message: `Async run ${asyncId} is live but does not have an async directory to interrupt.` };
 	}
-	const status = readAsyncStatus(input.target.asyncDir);
+	const status = reconcileAsyncRun(input.target.asyncDir, { resultsDir: input.resultsDir, kill: input.kill, now: input.now }).status;
 	if (!status || status.state !== "running" || typeof status.pid !== "number") {
 		return { ok: false, message: `Async run ${asyncId} is live but no interrupt-capable runner pid was found.` };
 	}
 	try {
-		(input.kill ?? process.kill)(status.pid, ASYNC_RESUME_INTERRUPT_SIGNAL);
+		deliverInterruptRequest({
+			asyncDir: input.target.asyncDir,
+			pid: status.pid,
+			kill: input.kill,
+			signal: ASYNC_RESUME_INTERRUPT_SIGNAL,
+			now: input.now,
+			source: "async-resume",
+		});
 		const tracked = input.state?.asyncJobs.get(asyncId);
 		if (tracked) {
 			tracked.activityState = undefined;

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

@@ -0,0 +1,177 @@
+/**
+ * Cross-OS control channel for async subagent runs.
+ *
+ * Background runs are detached OS processes. The original control path delivered
+ * an interrupt with `process.kill(pid, SIGUSR2|SIGBREAK)`, but Windows cannot
+ * deliver those signals cross-process via `process.kill` and throws `ENOSYS`,
+ * which left async runs uninterruptible (no stop, no live steer) on Windows.
+ *
+ * This module adds a portable, file-based control inbox inside the run directory.
+ * The parent drops an interrupt request file; the runner watches the inbox and
+ * routes the request into its existing graceful `interruptRunner()` (pause +
+ * resumable), identically on every platform. The OS signal is kept only as an
+ * opportunistic fast-path; its failure is non-fatal because the file inbox is
+ * authoritative.
+ */
+
+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";
+
+/**
+ * Opportunistic fast-path interrupt signal. On Unix `SIGUSR2` is trapped by the
+ * runner; on Windows `process.kill(pid, "SIGBREAK")` is not deliverable
+ * cross-process and throws `ENOSYS`, so the file inbox below is the real channel.
+ */
+export const INTERRUPT_SIGNAL: NodeJS.Signals = process.platform === "win32" ? "SIGBREAK" : "SIGUSR2";
+
+export type ControlChannelFs = Pick<typeof fs, "mkdirSync" | "existsSync" | "rmSync" | "watch">;
+export type ControlChannelTimers = { setInterval: typeof setInterval; clearInterval: typeof clearInterval };
+type KillFn = (pid: number, signal?: NodeJS.Signals | 0) => unknown;
+
+export interface InterruptRequest {
+	type: "interrupt";
+	ts?: number;
+	source?: string;
+	reason?: string;
+}
+
+/** Control inbox directory inside an async run dir. */
+export function controlInboxDir(asyncDir: string): string {
+	return path.join(asyncDir, "control");
+}
+
+/** Path of the portable interrupt request file. */
+export function interruptRequestPath(asyncDir: string): string {
+	return path.join(controlInboxDir(asyncDir), "interrupt.json");
+}
+
+/**
+ * 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.
+ */
+export function requestAsyncInterrupt(
+	asyncDir: string,
+	payload: Omit<InterruptRequest, "type"> = {},
+	deps: { now?: () => number } = {},
+): string {
+	const requestPath = interruptRequestPath(asyncDir);
+	const request: InterruptRequest = { ...payload, ts: payload.ts ?? deps.now?.() ?? Date.now(), type: "interrupt" };
+	writeAtomicJson(requestPath, request);
+	return requestPath;
+}
+
+/**
+ * Runner side: consume a pending interrupt request. Idempotent — removes the file
+ * so each distinct request fires exactly once. Returns whether one was pending.
+ */
+export function consumeInterruptRequest(
+	asyncDir: string,
+	fsImpl: Pick<typeof fs, "existsSync" | "rmSync"> = fs,
+): boolean {
+	const requestPath = interruptRequestPath(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
+ * is swallowed because the file inbox is authoritative there. Other signal
+ * failures are surfaced because they usually mean the runner is not alive to
+ * consume the request.
+ */
+export function deliverInterruptRequest(input: {
+	asyncDir: string;
+	pid?: number;
+	kill?: KillFn;
+	signal?: NodeJS.Signals;
+	now?: () => number;
+	source?: string;
+}): void {
+	const requestPath = requestAsyncInterrupt(input.asyncDir, input.source ? { source: input.source } : {}, { now: input.now });
+	if (typeof input.pid === "number" && input.pid > 0) {
+		try {
+			(input.kill ?? process.kill)(input.pid, input.signal ?? INTERRUPT_SIGNAL);
+		} catch (error) {
+			if ((error as NodeJS.ErrnoException | undefined)?.code === "ENOSYS") {
+				// File inbox is authoritative when custom cross-process signals are unavailable.
+				return;
+			}
+			try {
+				fs.rmSync(requestPath, { force: true });
+			} catch {
+				// Best effort cleanup; the caller still gets the signal failure.
+			}
+			throw error;
+		}
+	}
+}
+
+/**
+ * Runner side: watch the control inbox and route interrupt requests into
+ * `onInterrupt`. Uses `fs.watch` when available plus an interval poll as a
+ * portable safety net (covers filesystems/platforms where `fs.watch` is
+ * unreliable). Fires once per distinct request. Returns a disposer.
+ */
+export function watchAsyncControlInbox(
+	asyncDir: string,
+	opts: {
+		onInterrupt: () => void;
+		pollIntervalMs?: number;
+		fs?: ControlChannelFs;
+		timers?: ControlChannelTimers;
+	},
+): () => void {
+	const fsImpl = opts.fs ?? fs;
+	const timers = opts.timers ?? { setInterval, clearInterval };
+	const dir = controlInboxDir(asyncDir);
+	try {
+		fsImpl.mkdirSync(dir, { recursive: true });
+	} catch {
+		// Best effort — the poll/watch below tolerates a missing dir.
+	}
+
+	let disposed = false;
+	const check = (): void => {
+		if (disposed) return;
+		try {
+			if (consumeInterruptRequest(asyncDir, fsImpl)) opts.onInterrupt();
+		} catch {
+			// Never let inbox errors crash the runner.
+		}
+	};
+
+	// Handle a request that may have arrived before the watcher started.
+	check();
+
+	let watcher: fs.FSWatcher | undefined;
+	try {
+		watcher = fsImpl.watch(dir, () => check());
+		watcher.on?.("error", () => {
+			// fs.watch can emit on transient FS errors; the interval poll keeps us live.
+		});
+	} catch {
+		watcher = undefined;
+	}
+
+	const interval = timers.setInterval(check, opts.pollIntervalMs ?? POLL_INTERVAL_MS);
+	interval.unref?.();
+
+	return () => {
+		if (disposed) return;
+		disposed = true;
+		try {
+			watcher?.close();
+		} catch {
+			// ignore
+		}
+		timers.clearInterval(interval);
+	};
+}

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

@@ -21,7 +21,7 @@ import { projectNestedRegistryForRoot, sanitizeSummary } from "../shared/nested-
 const WATCHER_RESTART_DELAY_MS = 3000;
 const POLL_INTERVAL_MS = 3000;
 
-type ResultWatcherFs = Pick<typeof fs, "existsSync" | "readFileSync" | "unlinkSync" | "readdirSync" | "mkdirSync" | "watch">;
+type ResultWatcherFs = Pick<typeof fs, "existsSync" | "readFileSync" | "unlinkSync" | "readdirSync" | "mkdirSync" | "realpathSync" | "watch">;
 
 type ResultWatcherTimers = {
 	setTimeout: typeof setTimeout;
@@ -91,6 +91,14 @@ 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 },
 	state: SubagentState,
@@ -264,7 +272,8 @@ export function createResultWatcher(
 			state.watcherRestartTimer = null;
 		}
 		try {
-			state.watcher = fsApi.watch(resultsDir, (ev, file) => {
+			const watchDir = resolveNativeWatchDir(fsApi, resultsDir);
+			state.watcher = fsApi.watch(watchDir, (ev, file) => {
 				if (ev !== "rename" || !file) return;
 				const fileName = file.toString();
 				if (!fileName.endsWith(".json")) return;

package/src/runs/background/stale-run-reconciler.ts

@@ -48,9 +48,14 @@ function isNotFoundError(error: unknown): boolean {
 		&& (error as NodeJS.ErrnoException).code === "ENOENT";
 }
 
-function appendJsonl(filePath: string, payload: object): void {
-	fs.mkdirSync(path.dirname(filePath), { recursive: true });
-	fs.appendFileSync(filePath, `${JSON.stringify(payload)}\n`, "utf-8");
+function appendJsonlBestEffort(filePath: string, payload: object): void {
+	try {
+		fs.mkdirSync(path.dirname(filePath), { recursive: true });
+		fs.appendFileSync(filePath, `${JSON.stringify(payload)}\n`, "utf-8");
+	} catch {
+		// Repair status/result writes are the important path. A broken or full
+		// diagnostic event log must not make stale-run reconciliation fail.
+	}
 }
 
 function readStatusFile(asyncDir: string): AsyncStatus | null {
@@ -223,7 +228,7 @@ function writeFailedRepair(asyncDir: string, status: AsyncStatus, resultPath: st
 	const repair = buildFailedRepair(status, asyncDir, now, reason);
 	writeAtomicJson(resultPath, repair.result);
 	writeAtomicJson(path.join(asyncDir, "status.json"), repair.status);
-	appendJsonl(path.join(asyncDir, "events.jsonl"), {
+	appendJsonlBestEffort(path.join(asyncDir, "events.jsonl"), {
 		type: "subagent.run.repaired_stale",
 		ts: now,
 		runId: repair.status.runId,

package/src/runs/background/subagent-runner.ts

@@ -4,7 +4,8 @@ import * as path from "node:path";
 import { pathToFileURL } from "node:url";
 import type { Message } from "@earendil-works/pi-ai";
 import { writeAtomicJson } from "../../shared/atomic-json.ts";
-import { appendJsonl, getArtifactPaths } from "../../shared/artifacts.ts";
+import { consumeInterruptRequest, watchAsyncControlInbox } from "./control-channel.ts";
+import { appendJsonl as appendRawJsonl, getArtifactPaths } from "../../shared/artifacts.ts";
 import { PI_CODING_AGENT_PACKAGE, getPiSpawnCommand, resolveInstalledPiPackageRoot } from "../shared/pi-spawn.ts";
 import { captureSingleOutputSnapshot, finalizeSingleOutput, formatSavedOutputReference, resolveSingleOutput, type SingleOutputSnapshot } from "../shared/single-output.ts";
 import {
@@ -131,6 +132,79 @@ interface StepResult {
 }
 
 const ASYNC_INTERRUPT_SIGNAL: NodeJS.Signals = process.platform === "win32" ? "SIGBREAK" : "SIGUSR2";
+const DEFAULT_MAX_ASYNC_EVENTS_BYTES = 50 * 1024 * 1024;
+const ASYNC_EVENTS_MAX_BYTES_ENV = "PI_SUBAGENT_ASYNC_EVENTS_MAX_BYTES";
+const TRUNCATED_EVENT_TYPE = "subagent.events.truncated";
+const TRUNCATION_MARKER_RESERVE_BYTES = 512;
+
+interface AsyncEventLogState {
+	bytes: number;
+	diagnosticsTruncated: boolean;
+}
+
+const asyncEventLogStates = new Map<string, AsyncEventLogState>();
+
+function maxAsyncEventsBytes(): number {
+	const raw = process.env[ASYNC_EVENTS_MAX_BYTES_ENV];
+	if (!raw) return DEFAULT_MAX_ASYNC_EVENTS_BYTES;
+	const parsed = Number(raw);
+	if (!Number.isFinite(parsed) || parsed < 0) return DEFAULT_MAX_ASYNC_EVENTS_BYTES;
+	return Math.floor(parsed);
+}
+
+function eventLogState(filePath: string): AsyncEventLogState {
+	let state = asyncEventLogStates.get(filePath);
+	if (state) return state;
+	let bytes = 0;
+	try {
+		bytes = fs.statSync(filePath).size;
+	} catch (error) {
+		if ((error as NodeJS.ErrnoException).code !== "ENOENT") {
+			// Diagnostic event accounting is best-effort; writes below are also safe.
+		}
+	}
+	state = { bytes, diagnosticsTruncated: false };
+	asyncEventLogStates.set(filePath, state);
+	return state;
+}
+
+function appendJsonl(filePath: string, line: string): void {
+	try {
+		appendRawJsonl(filePath, line);
+		const state = asyncEventLogStates.get(filePath);
+		if (state) state.bytes += Buffer.byteLength(`${line}\n`, "utf-8");
+	} catch {
+		// Async event logging is diagnostic and must not fail the run.
+	}
+}
+
+function appendDiagnosticJsonl(filePath: string, line: string, droppedEventType?: string): void {
+	if (!line.trim()) return;
+	const state = eventLogState(filePath);
+	if (state.diagnosticsTruncated) return;
+	const maxBytes = maxAsyncEventsBytes();
+	const chunkBytes = Buffer.byteLength(`${line}\n`, "utf-8");
+	const diagnosticBudget = Math.max(0, maxBytes - TRUNCATION_MARKER_RESERVE_BYTES);
+	if (state.bytes + chunkBytes <= diagnosticBudget) {
+		appendJsonl(filePath, line);
+		return;
+	}
+
+	const marker = JSON.stringify({
+		type: TRUNCATED_EVENT_TYPE,
+		ts: Date.now(),
+		maxBytes,
+		droppedEventType,
+	});
+	if (state.bytes + Buffer.byteLength(`${marker}\n`, "utf-8") <= maxBytes) {
+		appendJsonl(filePath, marker);
+	}
+	state.diagnosticsTruncated = true;
+}
+
+function shouldPersistChildEvent(event: Record<string, unknown>): boolean {
+	return event.type !== "message_update";
+}
 
 function findLatestSessionFile(sessionDir: string): string | null {
 	try {
@@ -274,14 +348,15 @@ function runPiStreaming(
 
 		const appendChildEvent = (event: Record<string, unknown>) => {
 			if (!childEventContext) return;
-			appendJsonl(childEventContext.eventsPath, JSON.stringify({
+			if (!shouldPersistChildEvent(event)) return;
+			appendDiagnosticJsonl(childEventContext.eventsPath, JSON.stringify({
 				...event,
 				subagentSource: "child",
 				subagentRunId: childEventContext.runId,
 				subagentStepIndex: childEventContext.stepIndex,
 				subagentAgent: childEventContext.agent,
 				observedAt: Date.now(),
-			}));
+			}), typeof event.type === "string" ? event.type : undefined);
 		};
 
 		const appendChildLine = (type: "subagent.child.stdout" | "subagent.child.stderr", line: string) => {
@@ -676,6 +751,7 @@ async function runSingleStep(
 			}
 		}
 		const { args, env, tempDir } = buildPiArgs({
+			parentSessionId: step.parentSessionId,
 			baseArgs: ["--mode", "json", "-p"],
 			task,
 			sessionEnabled,
@@ -684,6 +760,7 @@ async function runSingleStep(
 			model: candidate,
 			inheritProjectContext: step.inheritProjectContext,
 			inheritSkills: step.inheritSkills,
+			requireReadTool: Boolean(step.skills?.length),
 			tools: step.tools,
 			extensions: step.extensions,
 			subagentOnlyExtensions: step.subagentOnlyExtensions,
@@ -1431,6 +1508,7 @@ async function runSubagent(config: SubagentRunConfig): Promise<void> {
 	}
 
 	const interruptRunner = () => {
+		consumeInterruptRequest(asyncDir);
 		if (interrupted || statusPayload.state !== "running") return;
 		interrupted = true;
 		const now = Date.now();
@@ -1456,6 +1534,10 @@ async function runSubagent(config: SubagentRunConfig): Promise<void> {
 		activeChildInterrupt?.();
 	};
 	process.on(ASYNC_INTERRUPT_SIGNAL, interruptRunner);
+	// Portable control inbox: the parent drops an interrupt request file here when
+	// it cannot deliver the OS signal (e.g. ENOSYS on Windows). Routes into the
+	// same graceful interruptRunner() so stop/steer work on every platform.
+	const disposeControlInbox = watchAsyncControlInbox(asyncDir, { onInterrupt: interruptRunner });
 	appendJsonl(
 		eventsPath,
 		JSON.stringify({
@@ -2241,6 +2323,7 @@ async function runSubagent(config: SubagentRunConfig): Promise<void> {
 		clearInterval(activityTimer);
 		activityTimer = undefined;
 	}
+	disposeControlInbox();
 	const effectiveSessionFile = sessionFile ?? latestSessionFile;
 	const runEndedAt = Date.now();
 	statusPayload.state = interrupted ? "paused" : results.every((r) => r.success) ? "complete" : "failed";