pi-subagents 0.40.0 → 0.41.0

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

@@ -46,11 +46,10 @@ import {
 	type BackgroundWorkSnapshot,
 	type RegisteredBackgroundWorkItem,
 } from "../../api/background-work.ts";
-import { listAsyncRuns, type AsyncRunSummary } from "./async-status.ts";
+import { formatAsyncRunList, listAsyncRuns, type AsyncRunSummary } from "./async-status.ts";
 import {
-	ASYNC_DIR,
+	DIRS,
 	INTERCOM_DETACH_REQUEST_EVENT,
-	RESULTS_DIR,
 	SUBAGENT_ASYNC_COMPLETE_EVENT,
 	SUBAGENT_FOREGROUND_COMPLETE_EVENT,
 	SUBAGENT_CONTROL_EVENT,
@@ -60,7 +59,7 @@ import {
 	type ForegroundResumeRun,
 	type SubagentState,
 } from "../../shared/types.ts";
-import { formatDuration } from "../../shared/formatters.ts";
+import { formatDuration, shortenPath } from "../../shared/formatters.ts";
 export { WAIT_TOOL_ENABLED_ENV, resolveWaitToolConfig, type ResolvedWaitToolConfig } from "./wait-config.ts";
 
 /** States that mean a run is still in flight (not yet resolved). */
@@ -73,6 +72,8 @@ const DEFAULT_POLL_INTERVAL_MS = 1000;
 export interface SubagentWaitParams {
 	/** Optional run id/prefix to wait for. When omitted, waits across every active run in this session. */
 	id?: string;
+	/** Arm a durable exact-run wake subscription and return immediately. Requires id. */
+	nonBlocking?: boolean;
 	/**
 	 * When true, block until EVERY active run in this session (or matching `id`)
 	 * is terminal. Default false: return as soon as the first run finishes, so a
@@ -106,6 +107,8 @@ export interface SubagentWaitDeps {
 	stopOnAttention?: boolean;
 	/** Internal auto-drain mode surfaces failed terminal subagent runs as errors. */
 	failOnFailedRuns?: boolean;
+	/** Arm a durable exact-target wait subscription in a long-lived interactive runtime. */
+	subscribe?: (input: { targetKind: "async" | "foreground"; runId: string; requestedId: string; timeoutMs: number }) => { token: string; expiresAt: number };
 	/** Injectable provider protocol surfaces for deterministic tests. */
 	backgroundWork?: {
 		snapshot(sessionId: string, nowMs: number): BackgroundWorkSnapshot;
@@ -253,8 +256,8 @@ function backgroundWorkForSession(deps: SubagentWaitDeps, nowMs: number): Backgr
 
 /** Queued/running runs from this session, including runs that need attention. */
 function activeRunsForSession(params: SubagentWaitParams, deps: SubagentWaitDeps): AsyncRunSummary[] {
-	const asyncDirRoot = deps.asyncDirRoot ?? ASYNC_DIR;
-	const resultsDir = deps.resultsDir ?? RESULTS_DIR;
+	const asyncDirRoot = deps.asyncDirRoot ?? DIRS.async;
+	const resultsDir = deps.resultsDir ?? DIRS.results;
 	const runs = listAsyncRuns(asyncDirRoot, {
 		states: [...ACTIVE_STATES],
 		sessionId: deps.state.currentSessionId ?? undefined,
@@ -273,8 +276,8 @@ function attentionRunsForSession(params: SubagentWaitParams, deps: SubagentWaitD
 
 /** All runs (any state) for this session, for the final summary. */
 function allRunsForSession(params: SubagentWaitParams, deps: SubagentWaitDeps): AsyncRunSummary[] {
-	const asyncDirRoot = deps.asyncDirRoot ?? ASYNC_DIR;
-	const resultsDir = deps.resultsDir ?? RESULTS_DIR;
+	const asyncDirRoot = deps.asyncDirRoot ?? DIRS.async;
+	const resultsDir = deps.resultsDir ?? DIRS.results;
 	const runs = listAsyncRuns(asyncDirRoot, {
 		sessionId: deps.state.currentSessionId ?? undefined,
 		resultsDir,
@@ -289,7 +292,8 @@ function summarizeTerminalRuns(runs: AsyncRunSummary[], providerFinishedCount =
 	if (runs.length === 0 && providerFinishedCount === 0) return "";
 	const counts = { complete: 0, failed: 0, paused: 0 } as Record<string, number>;
 	for (const run of runs) {
-		if (run.state in counts) counts[run.state] += 1;
+		const count = counts[run.state];
+		if (count !== undefined) counts[run.state] = count + 1;
 	}
 	const parts: string[] = [];
 	if (counts.complete) parts.push(`${counts.complete} complete`);
@@ -307,6 +311,25 @@ function result(text: string, isError = false): AgentToolResult<Details> {
 	};
 }
 
+/** Build the live status shown while async work keeps subagent_wait blocked. */
+function asyncWaitUpdate(runs: AsyncRunSummary[], providerCount: number, elapsedMs: number): AgentToolResult<Details> {
+	const activity = runs.flatMap((run) => {
+		const activeSteps = run.steps.filter((step) => step.status === "pending" || step.status === "running");
+		if (activeSteps.length === 0) {
+			return [`${run.id}: ${run.state}`];
+		}
+		return activeSteps.map((step) => {
+			const current = step.currentTool ?? (step.status === "pending" ? "queued" : "thinking…");
+			return `${step.agent}: ${current}${step.currentPath ? ` ${shortenPath(step.currentPath)}` : ""}`;
+		});
+	});
+	const headline = [
+		`Waiting ${formatDuration(elapsedMs)} for ${runs.length} async run(s) and ${providerCount} provider item(s).`,
+		...activity,
+	].join(" · ");
+	return result([headline, runs.length > 0 ? formatAsyncRunList(runs) : ""].filter(Boolean).join("\n"));
+}
+
 const TRANSCRIPT_TAIL_BYTES = 128 * 1024;
 const TRANSCRIPT_PREVIEW_LINES = 3;
 const TRANSCRIPT_PREVIEW_WIDTH = 220;
@@ -466,6 +489,12 @@ export async function waitForSubagents(
 	const timeoutMs = params.timeoutMs !== undefined && params.timeoutMs > 0 ? params.timeoutMs : DEFAULT_TIMEOUT_MS;
 	const startedAt = now();
 	const waitForAll = params.id ? true : params.all === true;
+	if (params.nonBlocking && !params.id) {
+		return result("Non-blocking wait subscriptions require id so the registration can bind one exact run identity.", true);
+	}
+	if (params.nonBlocking && params.all) {
+		return result("nonBlocking cannot be combined with all; subscribe to one exact run id.", true);
+	}
 
 	let active: AsyncRunSummary[];
 	let foreground: ForegroundResumeRun[];
@@ -489,6 +518,17 @@ export async function waitForSubagents(
 			return result(`Ambiguous subagent run id prefix "${params.id}" matched ${matches.length} active runs: ${matches.map((candidate) => candidate.id).join(", ")}. Pass a longer id.`, true);
 		}
 		const selected = matches[0];
+		if (selected && params.nonBlocking) {
+			if (!deps.subscribe) {
+				return result("Non-blocking wait subscriptions require a long-lived interactive subagent runtime; this runtime can only use blocking subagent_wait calls.", true);
+			}
+			try {
+				const registration = deps.subscribe({ targetKind: selected.kind, runId: selected.id, requestedId: params.id, timeoutMs });
+				return result(`Armed wait subscription ${registration.token} for exact ${selected.kind} run ${selected.id}. Returning immediately; this session will be woken on completion, failure, attention, reconciliation failure, or timeout. Inspect armed subscriptions with subagent({ action: "status" }).`);
+			} catch (error) {
+				return result(error instanceof Error ? error.message : String(error), true);
+			}
+		}
 		if (selected?.kind === "foreground") {
 			return waitForDetachedForegroundRun(selected.run, signal, deps, startedAt, now, pollIntervalMs, timeoutMs);
 		}
@@ -528,6 +568,7 @@ export async function waitForSubagents(
 			...activeInitialRuns.map((run) => `${run.id} (${run.state})`),
 			...activeInitialProviderItems.map((item) => `${item.provider}/${item.id}`),
 		].join(", ");
+		deps.onUpdate?.(asyncWaitUpdate(activeInitialRuns, activeInitialProviderItems.length, now() - startedAt));
 		if (signal?.aborted) {
 			return result(`Wait aborted after ${formatDuration(now() - startedAt)}. Still active: ${stillActive}.`, true);
 		}

package/src/runs/background/wait-subscriptions.ts

@@ -0,0 +1,253 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { randomUUID } from "node:crypto";
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { listAsyncRuns } from "./async-status.ts";
+import { writeAtomicJson } from "../../shared/atomic-json.ts";
+import {
+	DIRS,
+	INTERCOM_DETACH_REQUEST_EVENT,
+	SUBAGENT_ASYNC_COMPLETE_EVENT,
+	SUBAGENT_CONTROL_EVENT,
+	SUBAGENT_CONTROL_INTERCOM_EVENT,
+	SUBAGENT_FOREGROUND_COMPLETE_EVENT,
+	SUBAGENT_RESULT_INTERCOM_EVENT,
+	type SubagentState,
+	type WaitSubscriptionRecord,
+} from "../../shared/types.ts";
+
+const SUBSCRIPTION_VERSION = 1;
+const RECONCILE_INTERVAL_MS = 1_000;
+
+export interface ArmWaitSubscriptionInput {
+	targetKind: "async" | "foreground";
+	runId: string;
+	requestedId: string;
+	timeoutMs: number;
+}
+
+export interface WaitSubscriptionManager {
+	arm(input: ArmWaitSubscriptionInput): WaitSubscriptionRecord;
+	restore(): void;
+	reconcile(): void;
+	dispose(): void;
+}
+
+interface WaitSubscriptionManagerOptions {
+	asyncDirRoot?: string;
+	resultsDir?: string;
+	subscriptionsDir?: string;
+	now?: () => number;
+	pollIntervalMs?: number;
+	kill?: (pid: number, signal?: NodeJS.Signals | 0) => boolean;
+}
+
+function isNotFound(error: unknown): boolean {
+	return typeof error === "object" && error !== null && "code" in error && (error as NodeJS.ErrnoException).code === "ENOENT";
+}
+
+function parseRecord(value: unknown): WaitSubscriptionRecord | undefined {
+	if (!value || typeof value !== "object" || Array.isArray(value)) return undefined;
+	const record = value as Partial<WaitSubscriptionRecord>;
+	if (record.version !== SUBSCRIPTION_VERSION
+		|| typeof record.token !== "string"
+		|| !/^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i.test(record.token)
+		|| typeof record.sessionId !== "string"
+		|| (record.targetKind !== "async" && record.targetKind !== "foreground")
+		|| typeof record.runId !== "string"
+		|| typeof record.requestedId !== "string"
+		|| typeof record.createdAt !== "number"
+		|| typeof record.expiresAt !== "number") return undefined;
+	return record as WaitSubscriptionRecord;
+}
+
+function needsAttention(run: ReturnType<typeof listAsyncRuns>[number]): boolean {
+	return run.activityState === "needs_attention" || run.steps.some((step) => step.activityState === "needs_attention");
+}
+
+function subscriptionFile(dir: string, token: string): string {
+	return path.join(dir, `${token}.json`);
+}
+
+export function formatWaitSubscriptions(state: Pick<SubagentState, "waitSubscriptions">, now = Date.now()): string | undefined {
+	const subscriptions = [...(state.waitSubscriptions?.values() ?? [])].sort((left, right) => left.createdAt - right.createdAt);
+	if (subscriptions.length === 0) return undefined;
+	const lines = [`Armed wait subscriptions (${subscriptions.length}):`];
+	for (const record of subscriptions) {
+		lines.push(`- ${record.token}: ${record.targetKind} run ${record.runId}, timeout in ${Math.max(0, record.expiresAt - now)}ms`);
+	}
+	return lines.join("\n");
+}
+
+export function createWaitSubscriptionManager(
+	pi: Pick<ExtensionAPI, "events" | "sendMessage">,
+	state: SubagentState,
+	options: WaitSubscriptionManagerOptions = {},
+): WaitSubscriptionManager {
+	const asyncDirRoot = options.asyncDirRoot ?? DIRS.async;
+	const resultsDir = options.resultsDir ?? DIRS.results;
+	const subscriptionsDir = options.subscriptionsDir ?? path.join(path.dirname(asyncDirRoot), "wait-subscriptions");
+	const now = options.now ?? Date.now;
+	const subscriptions = state.waitSubscriptions ?? new Map<string, WaitSubscriptionRecord>();
+	state.waitSubscriptions = subscriptions;
+	const unresolvedRestoredForegroundTokens = new Set<string>();
+	let disposed = false;
+
+	const remove = (record: WaitSubscriptionRecord) => {
+		try {
+			fs.unlinkSync(subscriptionFile(subscriptionsDir, record.token));
+		} catch (error) {
+			if (!isNotFound(error)) throw error;
+		}
+		subscriptions.delete(record.token);
+		unresolvedRestoredForegroundTokens.delete(record.token);
+	};
+
+	const settle = (record: WaitSubscriptionRecord, outcome: string, detail: string) => {
+		if (disposed || state.currentSessionId !== record.sessionId) return;
+		try {
+			remove(record);
+		} catch (error) {
+			console.error(`Failed to clear wait subscription '${record.token}'; it remains armed:`, error);
+			return;
+		}
+		try {
+			pi.sendMessage({
+				customType: "subagent-wait-subscription",
+				content: `Wait subscription ${record.token} fired for run ${record.runId}: ${outcome}. ${detail}`,
+				display: true,
+				details: { token: record.token, runId: record.runId, outcome },
+			}, { triggerTurn: true });
+		} catch (error) {
+			console.error(`Failed to deliver wait subscription '${record.token}' after clearing it:`, error);
+		}
+	};
+
+	const reconcileRecord = (record: WaitSubscriptionRecord) => {
+		if (record.sessionId !== state.currentSessionId) return;
+		if (now() >= record.expiresAt) {
+			settle(record, "timed out", "The targeted run may still be active; inspect its status before taking follow-up action.");
+			return;
+		}
+		if (record.targetKind === "foreground") {
+			const run = state.foregroundRuns?.get(record.runId);
+			if (!run && unresolvedRestoredForegroundTokens.has(record.token)) return;
+			if (run) unresolvedRestoredForegroundTokens.delete(record.token);
+			if (!run || run.sessionId !== record.sessionId) {
+				settle(record, "could not be reconciled", "The remembered foreground run disappeared before completion was confirmed.");
+				return;
+			}
+			const detached = run.children.filter((child) => child.status === "detached");
+			if (detached.some((child) => child.activityState === "needs_attention")) {
+				settle(record, "needs attention", "Reply to the pending supervisor request or inspect the run status.");
+				return;
+			}
+			if (detached.length === 0) {
+				const failed = run.children.some((child) => child.status === "failed");
+				settle(record, failed ? "failed" : "completed", "Inspect the run status for its final output.");
+			}
+			return;
+		}
+
+		const runs = listAsyncRuns(asyncDirRoot, {
+			sessionId: record.sessionId,
+			runId: record.runId,
+			resultsDir,
+			kill: options.kill,
+			now,
+		});
+		const run = runs.find((candidate) => candidate.id === record.runId);
+		if (!run) {
+			settle(record, "could not be reconciled", "The exact async run disappeared before a terminal result was confirmed.");
+			return;
+		}
+		if (needsAttention(run)) {
+			settle(record, "needs attention", "Inspect the run status and answer any pending supervisor request.");
+			return;
+		}
+		if (run.state !== "queued" && run.state !== "running") {
+			settle(record, run.state === "complete" ? "completed" : run.state, "Inspect the run status for its final output.");
+		}
+	};
+
+	const reconcile = () => {
+		if (disposed || !state.currentSessionId) return;
+		for (const record of [...subscriptions.values()]) {
+			try {
+				reconcileRecord(record);
+			} catch (error) {
+				console.error(`Failed to reconcile wait subscription '${record.token}':`, error);
+				settle(record, "reconciliation failed", "The targeted run could not be reconciled. Inspect its status before taking follow-up action.");
+			}
+		}
+	};
+
+	const wakeChannels = [
+		INTERCOM_DETACH_REQUEST_EVENT,
+		SUBAGENT_ASYNC_COMPLETE_EVENT,
+		SUBAGENT_FOREGROUND_COMPLETE_EVENT,
+		SUBAGENT_CONTROL_EVENT,
+		SUBAGENT_CONTROL_INTERCOM_EVENT,
+		SUBAGENT_RESULT_INTERCOM_EVENT,
+	];
+	const unsubscribes = wakeChannels.map((channel) => pi.events.on(channel, reconcile));
+	const interval = setInterval(reconcile, options.pollIntervalMs ?? RECONCILE_INTERVAL_MS);
+	interval.unref?.();
+
+	return {
+		arm(input) {
+			const sessionId = state.currentSessionId;
+			if (!sessionId) throw new Error("A wait subscription requires an active session identity.");
+			const createdAt = now();
+			const record: WaitSubscriptionRecord = {
+				version: SUBSCRIPTION_VERSION,
+				token: randomUUID(),
+				sessionId,
+				targetKind: input.targetKind,
+				runId: input.runId,
+				requestedId: input.requestedId,
+				createdAt,
+				expiresAt: createdAt + input.timeoutMs,
+			};
+			fs.mkdirSync(subscriptionsDir, { recursive: true });
+			writeAtomicJson(subscriptionFile(subscriptionsDir, record.token), record);
+			subscriptions.set(record.token, record);
+			return record;
+		},
+		restore() {
+			subscriptions.clear();
+			unresolvedRestoredForegroundTokens.clear();
+			if (!state.currentSessionId) return;
+			let files: string[];
+			try {
+				files = fs.readdirSync(subscriptionsDir).filter((file) => file.endsWith(".json"));
+			} catch (error) {
+				if (isNotFound(error)) return;
+				throw error;
+			}
+			for (const file of files) {
+				try {
+					const record = parseRecord(JSON.parse(fs.readFileSync(path.join(subscriptionsDir, file), "utf-8")));
+					if (!record || file !== `${record.token}.json`) continue;
+					if (record.sessionId === state.currentSessionId) {
+						subscriptions.set(record.token, record);
+						if (record.targetKind === "foreground" && !state.foregroundRuns?.has(record.runId)) unresolvedRestoredForegroundTokens.add(record.token);
+					}
+				} catch (error) {
+					console.error(`Ignoring invalid wait subscription '${path.join(subscriptionsDir, file)}':`, error);
+				}
+			}
+			reconcile();
+		},
+		reconcile,
+		dispose() {
+			if (disposed) return;
+			disposed = true;
+			clearInterval(interval);
+			for (const unsubscribe of unsubscribes) {
+				try { unsubscribe(); } catch { /* best effort */ }
+			}
+			subscriptions.clear();
+		},
+	};
+}

package/src/runs/background/wait-tool.ts

@@ -2,8 +2,9 @@ import type { ExtensionAPI, ToolDefinition } from "@earendil-works/pi-coding-age
 import { SubagentWaitParams } from "../../extension/schemas.ts";
 import type { Details, SubagentState } from "../../shared/types.ts";
 import { resolveWaitToolConfig, waitForSubagents } from "./subagent-wait.ts";
+import type { WaitSubscriptionManager } from "./wait-subscriptions.ts";
 
-export function registerWaitTool(pi: ExtensionAPI, state: SubagentState, enabled = resolveWaitToolConfig().enabled): void {
+export function registerWaitTool(pi: ExtensionAPI, state: SubagentState, enabled = resolveWaitToolConfig().enabled, subscriptions?: Pick<WaitSubscriptionManager, "arm">): void {
 	const tool: ToolDefinition<typeof SubagentWaitParams, Details> = {
 		name: "subagent_wait",
 		label: "Subagent Wait",
@@ -14,12 +15,19 @@ In an interactive chat, do not call this merely to wait: return control to the u
 • { } — return when the first initially active async run or registered provider item finishes, or when a subagent needs attention.
 • { all: true } — wait for every async run and provider item that was active when the call began.
 • { id: "..." } — wait for one async or remembered detached foreground subagent run (id or prefix).
+• { id: "...", nonBlocking: true } — resolve the prefix once, persist an exact-run wake subscription, and return immediately. The originating interactive session wakes on completion, failure, attention, reconciliation failure, or timeout.
 • { timeoutMs: 600000 } — stop waiting after N ms; active work keeps running.
 
-Provider jobs are session-scoped and identified exactly, so replacing one job with another cannot hide a completion. Provider extensions must be explicitly loaded in this process. In a child agent, keep \`subagent_wait\` in the child tool allowlist and load each provider through the agent's extensions or subagentOnlyExtensions; this tool never loads providers or grants tools itself.${enabled ? "" : "\n\nConfigured behavior: subagent_wait is disabled by config.waitTool or PI_SUBAGENT_WAIT_TOOL_ENABLED and returns immediately without blocking."}`,
+Non-blocking subscriptions are visible in subagent status and differ from disabling waitTool: waitTool.enabled=false returns immediately without registering any future wake. Provider jobs are session-scoped and identified exactly, so replacing one job with another cannot hide a completion. Provider extensions must be explicitly loaded in this process. In a child agent, keep \`subagent_wait\` in the child tool allowlist and load each provider through the agent's extensions or subagentOnlyExtensions; this tool never loads providers or grants tools itself.${enabled ? "" : "\n\nConfigured behavior: subagent_wait is disabled by config.waitTool or PI_SUBAGENT_WAIT_TOOL_ENABLED and returns immediately without blocking."}`,
 		parameters: SubagentWaitParams,
-		execute(_id, params, signal, onUpdate) {
-			return waitForSubagents(params, signal, { state, events: pi.events, enabled, onUpdate });
+		execute(_id, params, signal, onUpdate, ctx) {
+			return waitForSubagents(params, signal, {
+				state,
+				events: pi.events,
+				enabled,
+				onUpdate,
+				...(subscriptions && ctx?.hasUI ? { subscribe: (input) => subscriptions.arm(input) } : {}),
+			});
 		},
 	};
 	pi.registerTool(tool);

package/src/runs/foreground/async-steering-action.ts

@@ -121,7 +121,7 @@ export async function steerAsyncRun(input: {
 	if (finalResult?.state === "delivered") {
 		return { content: [{ type: "text", text: `Steering delivered for async run ${status.runId} (request ${requestId}).` }], details: { mode: "management", results: [], steering: finalResult } };
 	}
-	const running = (finalStatus?.steps ?? status.steps).filter((step) => step.status === "running");
+	const running = (finalStatus?.steps ?? status.steps ?? []).filter((step) => step.status === "running");
 	const recoveryAllowed = status.mode === "single" && status.isNested !== true && running.length === 1 && Boolean(finalStatus?.steering) && (input.index === undefined || input.index === 0);
 	if (recoveryAllowed && finalResult?.state !== "scheduled" && input.recover) {
 		const appendSteeringNotice = (state: "failed" | "recovered", message: string): void => {
@@ -194,7 +194,7 @@ export async function steerAsyncRun(input: {
 			const revived = await input.recover(limits);
 			if (revived.isError || !revived.details.asyncId) throw new Error(revived.content[0]?.type === "text" ? revived.content[0].text : "Replacement launch failed; source run remains paused.");
 			const sourceStatus = readStatus(asyncDir);
-			const targetIndex = input.index ?? status.steps.findIndex((step) => step.status === "running");
+			const targetIndex = input.index ?? status.steps?.findIndex((step) => step.status === "running") ?? -1;
 			if (sourceStatus?.state === "paused" && sourceStatus.steering && targetIndex >= 0) {
 				updateSteeringTarget(sourceStatus.steering, requestId, targetIndex, "recovered", Date.now(), { replacementRunId: revived.details.asyncId });
 				const stepSteering = sourceStatus.steps?.[targetIndex]?.steering;
@@ -207,7 +207,7 @@ export async function steerAsyncRun(input: {
 		} catch (error) {
 			const reason = error instanceof Error ? error.message : String(error);
 			const failedStatus = readStatus(asyncDir);
-			const targetIndex = input.index ?? status.steps.findIndex((step) => step.status === "running");
+			const targetIndex = input.index ?? status.steps?.findIndex((step) => step.status === "running") ?? -1;
 			if (failedStatus && failedStatus.state !== "running" && failedStatus.state !== "queued" && failedStatus.steering && targetIndex >= 0) {
 				updateSteeringTarget(failedStatus.steering, requestId, targetIndex, "failed", Date.now(), { reason });
 				const stepSteering = failedStatus.steps?.[targetIndex]?.steering;

package/src/runs/foreground/chain-clarify.ts

@@ -775,22 +775,26 @@ export class ChainClarifyComponent implements Component {
 
 	private handleEditInput(data: string): void {
 		const textWidth = this.width - 4; // Must match render: innerW - 2 = (width - 2) - 2
-		if (matchesKey(data, "shift+up") || matchesKey(data, "pageup")) {
+		if (matchesKey(data, "shift+up") || matchesKey(data, "pageUp")) {
 			const { lines: wrapped, starts } = wrapText(this.editState.buffer, textWidth);
 			const cursorPos = getCursorDisplayPos(this.editState.cursor, starts);
 			const targetLine = Math.max(0, cursorPos.line - this.EDIT_VIEWPORT_HEIGHT);
+			const targetStart = starts[targetLine];
+			if (targetStart === undefined) return;
 			const targetCol = Math.min(cursorPos.col, wrapped[targetLine]?.length ?? 0);
-			this.editState = { ...this.editState, cursor: starts[targetLine] + targetCol };
+			this.editState = { ...this.editState, cursor: targetStart + targetCol };
 			this.tui.requestRender();
 			return;
 		}
 
-		if (matchesKey(data, "shift+down") || matchesKey(data, "pagedown")) {
+		if (matchesKey(data, "shift+down") || matchesKey(data, "pageDown")) {
 			const { lines: wrapped, starts } = wrapText(this.editState.buffer, textWidth);
 			const cursorPos = getCursorDisplayPos(this.editState.cursor, starts);
 			const targetLine = Math.min(wrapped.length - 1, cursorPos.line + this.EDIT_VIEWPORT_HEIGHT);
+			const targetStart = starts[targetLine];
+			if (targetStart === undefined) return;
 			const targetCol = Math.min(cursorPos.col, wrapped[targetLine]?.length ?? 0);
-			this.editState = { ...this.editState, cursor: starts[targetLine] + targetCol };
+			this.editState = { ...this.editState, cursor: targetStart + targetCol };
 			this.tui.requestRender();
 			return;
 		}

package/src/runs/foreground/chain-execution.ts

@@ -44,7 +44,8 @@ import {
 import { buildChainSummary } from "../../shared/formatters.ts";
 import { compactForegroundDetails, getSingleResultOutput, mapConcurrent, resolveChildCwd, sumResultsCost, sumResultsUsage } from "../../shared/utils.ts";
 import { DEFAULT_GLOBAL_CONCURRENCY_LIMIT, Semaphore } from "../shared/parallel-utils.ts";
-import { formatParallelHandoffError, formatParallelHandoffReference, parallelHandoffPath, writeParallelHandoffGroup } from "../shared/parallel-handoff.ts";
+import type { PermissionConfig } from "../shared/permissions.ts";
+import { formatParallelHandoffError, formatParallelHandoffReference, parallelHandoffPath, writeParallelHandoffGroup, writePendingParallelHandoff } from "../shared/parallel-handoff.ts";
 import { recordRun } from "../shared/run-history.ts";
 import {
 	cleanupWorktrees,
@@ -165,6 +166,7 @@ interface ParallelChainRunInput {
 	configToolBudget?: ToolBudgetConfig;
 	globalSemaphore?: Semaphore;
 	capabilityCeiling?: ResolvedSubagentCapabilityCeiling;
+	permissions?: PermissionConfig;
 	dynamic?: boolean;
 }
 
@@ -228,30 +230,32 @@ function finalizeParallelWorktreeHandoff(input: {
 	results: SingleResult[];
 }): { output: string; reference?: NonNullable<Details["parallelHandoff"]> } {
 	const diffs = diffWorktrees(input.worktreeSetup, input.agents, path.join(input.artifactsDir, "worktree-diffs", input.runId, `step-${input.stepIndex}`));
-	const cleanup = cleanupWorktrees(input.worktreeSetup);
 	const diffSummary = formatWorktreeDiffSummary(diffs);
+	const manifestPath = parallelHandoffPath(input.artifactsDir, input.runId);
+	const handoff = {
+		manifestPath,
+		runId: input.runId,
+		mode: "chain" as const,
+		source: "foreground" as const,
+		cwd: input.cwd,
+		stepIndex: input.stepIndex,
+		flatStartIndex: input.flatStartIndex,
+		setup: input.worktreeSetup,
+		diffs,
+		results: input.results.map((result) => ({
+			agent: result.agent,
+			status: result.stopped ? "stopped" as const : result.detached ? "detached" as const : result.interrupted ? "paused" as const : result.exitCode === 0 ? "completed" as const : "failed" as const,
+			summary: getSingleResultOutput(result) || result.error || "(no output)",
+			...(result.artifactPaths?.outputPath ? { outputPath: result.artifactPaths.outputPath } : {}),
+			...(result.structuredOutput !== undefined ? { structuredOutput: result.structuredOutput } : {}),
+			...(result.structuredOutputPath ? { structuredOutputPath: result.structuredOutputPath } : {}),
+			...(result.sessionFile ? { sessionPath: result.sessionFile } : {}),
+		})),
+	};
 	try {
-		const reference = writeParallelHandoffGroup({
-			manifestPath: parallelHandoffPath(input.artifactsDir, input.runId),
-			runId: input.runId,
-			mode: "chain",
-			source: "foreground",
-			cwd: input.cwd,
-			stepIndex: input.stepIndex,
-			flatStartIndex: input.flatStartIndex,
-			setup: input.worktreeSetup,
-			diffs,
-			cleanup,
-			results: input.results.map((result) => ({
-				agent: result.agent,
-				status: result.stopped ? "stopped" : result.detached ? "detached" : result.interrupted ? "paused" : result.exitCode === 0 ? "completed" : "failed",
-				summary: getSingleResultOutput(result) || result.error || "(no output)",
-				...(result.artifactPaths?.outputPath ? { outputPath: result.artifactPaths.outputPath } : {}),
-				...(result.structuredOutput !== undefined ? { structuredOutput: result.structuredOutput } : {}),
-				...(result.structuredOutputPath ? { structuredOutputPath: result.structuredOutputPath } : {}),
-				...(result.sessionFile ? { sessionPath: result.sessionFile } : {}),
-			})),
-		});
+		writeParallelHandoffGroup(handoff);
+		const cleanup = cleanupWorktrees(input.worktreeSetup, { kind: "preserve", capturedDiffs: diffs, handoffManifestPath: manifestPath });
+		const reference = writeParallelHandoffGroup({ ...handoff, cleanup });
 		const suffix = [diffSummary, formatParallelHandoffReference(reference)].filter(Boolean).join("\n\n");
 		return { output: suffix ? `${input.output}\n\n${suffix}` : input.output, reference };
 	} catch (error) {
@@ -381,6 +385,7 @@ async function runParallelChainTasks(input: ParallelChainRunInput): Promise<Sing
 			let result!: SingleResult;
 			try {
 				result = await runSync(input.ctx.cwd, input.agents, task.agent, taskStr, {
+				permissions: input.permissions,
 				parentSessionId: input.ctx.sessionManager.getSessionId() ?? undefined,
 				capabilityCeiling: input.capabilityCeiling,
 				context: input.contextForAgent?.(task.agent),
@@ -529,6 +534,7 @@ interface ChainExecutionParams {
 	toolBudget?: ResolvedToolBudget;
 	usageBudget?: UsageBudgetConfig;
 	configToolBudget?: ToolBudgetConfig;
+	permissions?: PermissionConfig;
 	/** Global cap on simultaneously-running tasks within this chain. Defaults to DEFAULT_GLOBAL_CONCURRENCY_LIMIT. */
 	globalConcurrencyLimit?: number;
 	capabilityCeiling?: ResolvedSubagentCapabilityCeiling;
@@ -627,10 +633,11 @@ export async function executeChain(params: ChainExecutionParams): Promise<ChainE
 		?? (isCheckpointStep(firstStep)
 			? undefined
 			: isParallelStep(firstStep)
-				? firstStep.parallel[0]!.task!
+				? firstStep.parallel[0]!.task
 				: isDynamicParallelStep(firstStep)
-					? firstStep.parallel.task!
-					: (firstStep as SequentialStep).task!);
+					? firstStep.parallel.task
+					: (firstStep as SequentialStep).task)
+		?? "";
 	try {
 		validateChainOutputBindings(chainSteps, { maxItems: params.dynamicFanoutMaxItems });
 	} catch (error) {
@@ -788,6 +795,18 @@ ${step.message}` : ""}` }],
 			}
 
 			try {
+				if (worktreeSetup) {
+					writePendingParallelHandoff({
+						manifestPath: parallelHandoffPath(artifactsDir, runId),
+						runId,
+						mode: "chain",
+						source: "foreground",
+						cwd: parallelCwd,
+						stepIndex,
+						flatStartIndex: globalTaskIndex,
+						setup: worktreeSetup,
+					});
+				}
 				const agentNames = step.parallel.map((task) => task.agent);
 				const parallelBehaviors = resolveParallelBehaviors(step.parallel, agents, stepIndex, chainSkills)
 					.map((behavior, taskIndex) => suppressProgressForReadOnlyTask(behavior, parallelTemplates[taskIndex] ?? step.parallel[taskIndex]?.task, originalTask));
@@ -854,6 +873,7 @@ ${step.message}` : ""}` }],
 					toolBudget: params.toolBudget,
 					configToolBudget: params.configToolBudget,
 					globalSemaphore,
+					permissions: params.permissions,
 				});
 				globalTaskIndex += step.parallel.length;
 
@@ -928,7 +948,7 @@ ${step.message}` : ""}` }],
 					.filter(({ result, task }) => isAgentContractV1(task?.agentContract ?? step.agentContract ?? params.agentContract) && (task?.gateOn ?? step.gateOn) === "acceptance" && result.acceptance?.status === "rejected");
 				if (acceptanceFailures.length > 0) {
 					const acceptanceSummary = acceptanceFailures
-						.map(({ result, originalIndex }) => `- Task ${originalIndex + 1} (${result.agent}): ${acceptanceFailureMessage(result.acceptance) ?? "acceptance rejected"}`)
+						.map(({ result, originalIndex }) => `- Task ${originalIndex + 1} (${result.agent}): ${(result.acceptance ? acceptanceFailureMessage(result.acceptance) : undefined) ?? "acceptance rejected"}`)
 						.join("\n");
 					const errorMsg = `Parallel step ${stepIndex + 1} acceptance gate failed:\n${acceptanceSummary}`;
 					const summary = buildChainSummary(chainSteps, results, chainDir, "failed", { index: stepIndex, error: errorMsg });
@@ -1024,7 +1044,9 @@ ${step.message}` : ""}` }],
 						cwd: cwd ?? ctx.cwd,
 						reportOptional: isAgentContractV1(step.agentContract ?? params.agentContract),
 					});
-					dynamicGroupStatuses[stepIndex].acceptance = groupAcceptance;
+					const dynamicGroupStatus = dynamicGroupStatuses[stepIndex];
+					if (!dynamicGroupStatus) throw new Error(`Missing dynamic group status at step ${stepIndex}`);
+					dynamicGroupStatus.acceptance = groupAcceptance;
 					const groupAcceptanceFailure = !isAgentContractV1(step.agentContract ?? params.agentContract) || step.gateOn === "acceptance" ? acceptanceFailureMessage(groupAcceptance) : undefined;
 					if (groupAcceptanceFailure) {
 						dynamicGroupStatuses[stepIndex] = { status: "failed", error: groupAcceptanceFailure, acceptance: groupAcceptance };
@@ -1112,6 +1134,7 @@ ${step.message}` : ""}` }],
 				toolBudget: params.toolBudget,
 				configToolBudget: params.configToolBudget,
 				globalSemaphore,
+				permissions: params.permissions,
 				dynamic: true,
 			});
 			globalTaskIndex = dynamicStartIndex + reservedDynamicItems;
@@ -1171,7 +1194,7 @@ ${step.message}` : ""}` }],
 				.filter(({ result, task }) => isAgentContractV1(task?.agentContract ?? dynamicParallelStep.agentContract ?? params.agentContract) && (task?.gateOn ?? dynamicParallelStep.gateOn) === "acceptance" && result.acceptance?.status === "rejected");
 			if (acceptanceFailures.length > 0) {
 				const acceptanceSummary = acceptanceFailures
-					.map(({ result, originalIndex }) => `- Item ${originalIndex + 1} (${result.agent}, key ${materialized.items[originalIndex]?.key ?? originalIndex}): ${acceptanceFailureMessage(result.acceptance) ?? "acceptance rejected"}`)
+					.map(({ result, originalIndex }) => `- Item ${originalIndex + 1} (${result.agent}, key ${materialized.items[originalIndex]?.key ?? originalIndex}): ${(result.acceptance ? acceptanceFailureMessage(result.acceptance) : undefined) ?? "acceptance rejected"}`)
 					.join("\n");
 				const errorMsg = `Dynamic step ${stepIndex + 1} acceptance gate failed:\n${acceptanceSummary}`;
 				dynamicGroupStatuses[stepIndex] = { status: "failed", error: errorMsg };
@@ -1217,7 +1240,9 @@ ${step.message}` : ""}` }],
 				cwd: cwd ?? ctx.cwd,
 				reportOptional: isAgentContractV1(step.agentContract ?? params.agentContract),
 			});
-			dynamicGroupStatuses[stepIndex].acceptance = groupAcceptance;
+			const dynamicGroupStatus = dynamicGroupStatuses[stepIndex];
+			if (!dynamicGroupStatus) throw new Error(`Missing dynamic group status at step ${stepIndex}`);
+			dynamicGroupStatus.acceptance = groupAcceptance;
 			const groupAcceptanceFailure = effectiveGroupAcceptance.explicit && (!isAgentContractV1(step.agentContract ?? params.agentContract) || step.gateOn === "acceptance") ? acceptanceFailureMessage(groupAcceptance) : undefined;
 			if (groupAcceptanceFailure) {
 				dynamicGroupStatuses[stepIndex] = { status: "failed", error: groupAcceptanceFailure, acceptance: groupAcceptance };
@@ -1340,6 +1365,7 @@ ${step.message}` : ""}` }],
 					dynamicGroupStatuses,
 				});
 				r = await runSync(ctx.cwd, agents, seqStep.agent, stepTask, {
+				permissions: params.permissions,
 				parentSessionId: ctx.sessionManager.getSessionId() ?? undefined,
 				capabilityCeiling: params.capabilityCeiling,
 				context: params.contextForAgent?.(seqStep.agent),