@selesai/code 0.9.11 → 0.9.12

package/dist/extensions/pi-subagents/src/runs/background/subagent-wait.ts

@@ -86,6 +86,8 @@ export interface SubagentWaitParams {
 	all?: boolean;
 	/** Give up after this many milliseconds. Defaults to 30 minutes. */
 	timeoutMs?: number;
+	/** False keeps a blocking wait open through idle attention; supervisor/contact requests still stop the wait. */
+	stopOnAttention?: boolean;
 }
 
 /** Minimal event-bus surface wait subscribes to (matches pi.events). */
@@ -110,6 +112,8 @@ export interface SubagentWaitDeps {
 	stopOnAttention?: boolean;
 	/** Internal auto-drain mode surfaces failed terminal subagent runs as errors. */
 	failOnFailedRuns?: boolean;
+	/** Internal auto-drain mode surfaces actionable attention as an error. */
+	failOnAttention?: 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. */
@@ -226,7 +230,7 @@ function summarizeForegroundChildren(run: ForegroundResumeRun, indices: Set<numb
 }
 
 function foregroundChildrenNeedingAttention(run: ForegroundResumeRun, indices: Set<number>) {
-	return run.children.filter((child) => indices.has(child.index) && child.status === "detached" && child.activityState === "needs_attention");
+	return run.children.filter((child) => indices.has(child.index) && child.status === "detached" && child.activityState === "needs_attention" && child.currentTool === "contact_supervisor");
 }
 
 function formatForegroundAttention(run: ForegroundResumeRun, children: ReturnType<typeof foregroundChildrenNeedingAttention>, elapsedMs: number): AgentToolResult<Details> {
@@ -278,19 +282,19 @@ function attentionRunsForSession(params: SubagentWaitParams, deps: SubagentWaitD
 	return activeRunsForSession(params, deps).filter((run) => needsAttention(run) && initialIds.has(run.id));
 }
 
-/** All runs (any state) for this session, for the final summary. */
-function allRunsForSession(params: SubagentWaitParams, deps: SubagentWaitDeps): AsyncRunSummary[] {
+/** Exact initial runs in any state, for the final summary. */
+function runsForIds(runIds: Iterable<string>, deps: SubagentWaitDeps): AsyncRunSummary[] {
 	const asyncDirRoot = deps.asyncDirRoot ?? DIRS.async;
 	const resultsDir = deps.resultsDir ?? DIRS.results;
-	const runs = listAsyncRuns(asyncDirRoot, {
+	return [...runIds].flatMap((runId) => listAsyncRuns(asyncDirRoot, {
 		sessionId: deps.state.currentSessionId ?? undefined,
 		resultsDir,
 		kill: deps.kill,
 		now: deps.now,
 		includeNested: false,
-		...(params.id ? { runId: params.id } : {}),
-	});
-	return params.id ? runs.filter((run) => matchesId(run, params.id!)) : runs;
+		runId,
+		exactRunId: true,
+	}));
 }
 
 function summarizeTerminalRuns(runs: AsyncRunSummary[], providerFinishedCount = 0): string {
@@ -453,7 +457,7 @@ async function waitForDetachedForegroundRun(
 			return result(`Remembered foreground run "${run.runId}" disappeared before a terminal child result was recorded. Completion cannot be confirmed; do not launch a replacement without checking the originating child session.`, true);
 		}
 		const pending = current.children.filter((child) => initialDetachedIndices.has(child.index) && child.status === "detached");
-		const attention = deps.stopOnAttention === false ? [] : foregroundChildrenNeedingAttention(current, initialDetachedIndices);
+		const attention = foregroundChildrenNeedingAttention(current, initialDetachedIndices);
 		if (attention.length > 0) return formatForegroundAttention(current, attention, now() - startedAt);
 		if (pending.length === 0) {
 			const outcome = summarizeForegroundChildren(current, initialDetachedIndices);
@@ -555,11 +559,11 @@ export async function waitForSubagents(
 	const initialProviderIds = new Set(providerActive.map(backgroundWorkIdentity));
 	const initialProviderNames = new Set(providerActive.map((item) => item.provider));
 	const initialCount = initialAsyncIds.size + initialProviderIds.size;
-	const stopOnAttention = deps.stopOnAttention !== false;
+	const stopOnAttention = params.stopOnAttention ?? deps.stopOnAttention !== false;
 	let attention = active.filter((run) => needsAttention(run));
 
 	const isDone = (): boolean => {
-		if (stopOnAttention && attention.some((run) => initialAsyncIds.has(run.id))) return true;
+		if (attention.some((run) => initialAsyncIds.has(run.id) && (stopOnAttention || hasSupervisorTool(run)))) return true;
 		const activeAsyncIds = new Set(active.map((run) => run.id));
 		const activeProviderIds = new Set(providerActive.map(backgroundWorkIdentity));
 		if (waitForAll) {
@@ -611,7 +615,7 @@ export async function waitForSubagents(
 	const activeProviderIds = new Set(providerActive.map(backgroundWorkIdentity));
 	const providerFinishedCount = [...initialProviderIds].filter((id) => !activeProviderIds.has(id)).length;
 	try {
-		const allNow = allRunsForSession(waitParams, deps);
+		const allNow = runsForIds(initialAsyncIds, deps);
 		const terminal = allNow.filter((run) => !ACTIVE_STATES.includes(run.state) && initialAsyncIds.has(run.id));
 		finishedAsyncCount = terminal.length;
 		failedAsyncCount = terminal.filter((run) => run.state === "failed").length;
@@ -643,7 +647,7 @@ export async function waitForSubagents(
 		const status = relevantAttention.length > 0 ? "attention required" : "done";
 		return result(
 			`Waited ${elapsed} for ${scope}; ${status}.${outcome}${resumeGuidance}${attentionNote} Completion/control events have been observed; inspect status if a notification is not visible yet.`,
-			deps.failOnFailedRuns === true && failedAsyncCount > 0,
+			(deps.failOnFailedRuns === true && failedAsyncCount > 0) || (deps.failOnAttention === true && relevantAttention.length > 0),
 			completions,
 		);
 	}
@@ -660,7 +664,7 @@ export async function waitForSubagents(
 		: `${finishedCount} of ${initialCount} ${subject} finished`;
 	return result(
 		`Waited ${elapsed}; ${progress}.${outcome}${resumeGuidance}${attentionNote}${remainder} Relevant completion/control events have been observed; inspect status if a notification is not visible yet.`,
-		deps.failOnFailedRuns === true && failedAsyncCount > 0,
+		(deps.failOnFailedRuns === true && failedAsyncCount > 0) || (deps.failOnAttention === true && relevantAttention.length > 0),
 		completions,
 	);
 }

package/dist/extensions/pi-subagents/src/runs/background/terminal-run-index.ts

@@ -0,0 +1,138 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import type { AsyncStatus } from "../../shared/types.ts";
+import { readStatus } from "../../shared/utils.ts";
+import { writeAtomicJson } from "../../shared/atomic-json.ts";
+import { encodeIndexSegment } from "./index-segment.ts";
+
+export const TERMINAL_RUN_INDEX_DIR = ".terminal-runs";
+
+const TERMINAL_RUN_INDEX_VERSION = 1;
+const TIMESTAMP_WIDTH = 16;
+
+interface TerminalRunIndexEntry {
+	version: 1;
+	runId: string;
+	sessionId: string;
+	endedAt: number;
+}
+
+function isTerminalState(state: AsyncStatus["state"]): boolean {
+	return state === "complete" || state === "failed" || state === "paused" || state === "stopped" || state === "rejected";
+}
+
+function indexRoot(asyncDirRoot: string): string {
+	return path.join(asyncDirRoot, TERMINAL_RUN_INDEX_DIR);
+}
+
+function sessionIndexDir(asyncDirRoot: string, sessionId: string): string {
+	return path.join(indexRoot(asyncDirRoot), encodeIndexSegment(sessionId));
+}
+
+function markerName(endedAt: number, runId: string): string {
+	return `${Math.max(0, Math.floor(endedAt)).toString().padStart(TIMESTAMP_WIDTH, "0")}-${encodeIndexSegment(runId)}.json`;
+}
+
+function markerPath(asyncDir: string, sessionId: string, endedAt: number): string {
+	return path.join(sessionIndexDir(path.dirname(asyncDir), sessionId), markerName(endedAt, path.basename(asyncDir)));
+}
+
+function parseEntry(value: unknown): TerminalRunIndexEntry | undefined {
+	if (!value || typeof value !== "object" || Array.isArray(value)) return undefined;
+	const entry = value as Partial<TerminalRunIndexEntry>;
+	if (entry.version !== TERMINAL_RUN_INDEX_VERSION
+		|| typeof entry.runId !== "string" || !entry.runId
+		|| typeof entry.sessionId !== "string" || !entry.sessionId
+		|| typeof entry.endedAt !== "number" || !Number.isFinite(entry.endedAt)) return undefined;
+	return { version: TERMINAL_RUN_INDEX_VERSION, runId: entry.runId, sessionId: entry.sessionId, endedAt: entry.endedAt };
+}
+
+export function updateTerminalRunIndex(asyncDir: string, status: AsyncStatus): void {
+	if (!isTerminalState(status.state) || typeof status.sessionId !== "string" || !status.sessionId) return;
+	const endedAt = status.endedAt ?? status.lastUpdate ?? status.startedAt;
+	const marker = markerPath(asyncDir, status.sessionId, endedAt);
+	const entry: TerminalRunIndexEntry = {
+		version: TERMINAL_RUN_INDEX_VERSION,
+		runId: status.runId || path.basename(asyncDir),
+		sessionId: status.sessionId,
+		endedAt,
+	};
+	writeAtomicJson(marker, entry);
+}
+
+function removeInvalidMarker(marker: string): void {
+	try {
+		fs.rmSync(marker, { force: true });
+	} catch {
+		// An advisory marker can remain for a later read when cleanup is contended.
+	}
+}
+
+interface MarkerFile {
+	dir: string;
+	name: string;
+}
+
+function markerFiles(dir: string): MarkerFile[] {
+	try {
+		return fs.readdirSync(dir, { withFileTypes: true })
+			.filter((entry) => entry.isFile() && entry.name.endsWith(".json"))
+			.map((entry) => ({ dir, name: entry.name }));
+	} catch (error) {
+		const code = (error as NodeJS.ErrnoException).code;
+		if (code === "ENOENT" || code === "ENOTDIR") return [];
+		throw error;
+	}
+}
+
+function sessionDirs(asyncDirRoot: string, sessionId: string | undefined): string[] {
+	if (sessionId) return [sessionIndexDir(asyncDirRoot, sessionId)];
+	try {
+		return fs.readdirSync(indexRoot(asyncDirRoot), { withFileTypes: true })
+			.filter((entry) => entry.isDirectory())
+			.map((entry) => path.join(indexRoot(asyncDirRoot), entry.name));
+	} catch (error) {
+		const code = (error as NodeJS.ErrnoException).code;
+		if (code === "ENOENT" || code === "ENOTDIR") return [];
+		throw error;
+	}
+}
+
+function recentMarkerFiles(dirs: string[], limit: number): string[] {
+	return dirs.flatMap(markerFiles)
+		.sort((left, right) => right.name.localeCompare(left.name))
+		.slice(0, limit)
+		.map((marker) => path.join(marker.dir, marker.name));
+}
+
+export function readRecentTerminalRunIndex(asyncDirRoot: string, options: { sessionId?: string; limit?: number } = {}): string[] {
+	const limit = options.limit === undefined ? Number.POSITIVE_INFINITY : Math.max(0, Math.floor(options.limit));
+	const candidates = recentMarkerFiles(sessionDirs(asyncDirRoot, options.sessionId), limit);
+	const runIds: string[] = [];
+	const seen = new Set<string>();
+	for (const marker of candidates) {
+		let entry: TerminalRunIndexEntry | undefined;
+		try {
+			entry = parseEntry(JSON.parse(fs.readFileSync(marker, "utf-8")));
+		} catch (error) {
+			if ((error as NodeJS.ErrnoException).code === "ENOENT") continue;
+		}
+		if (!entry || (options.sessionId !== undefined && entry.sessionId !== options.sessionId)) {
+			removeInvalidMarker(marker);
+			continue;
+		}
+		const asyncDir = path.join(asyncDirRoot, entry.runId);
+		const status = readStatus(asyncDir);
+		if (!status || !isTerminalState(status.state) || status.sessionId !== entry.sessionId || (status.runId && status.runId !== entry.runId)) {
+			removeInvalidMarker(marker);
+			continue;
+		}
+		if (seen.has(entry.runId)) {
+			removeInvalidMarker(marker);
+			continue;
+		}
+		seen.add(entry.runId);
+		runIds.push(entry.runId);
+	}
+	return runIds;
+}

package/dist/extensions/pi-subagents/src/runs/background/wait-completions.ts

@@ -2,7 +2,7 @@ import * as fs from "node:fs";
 import type { ArtifactPaths, SubagentState, WaitCompletion, WaitCompletionChild } from "../../shared/types.ts";
 import type { AsyncRunSummary } from "./async-status.ts";
 import { readCompletionReplay, writeCompletionReplay } from "./completion-replay.ts";
-import { resultFilePath, resultPayloadPathForSessionRun } from "./result-files.ts";
+import { fallbackResultPayloadPathForSessionRun, resultFilePath, resultPayloadPathForSessionRun } from "./result-files.ts";
 
 function asNonEmptyString(value: unknown): string | undefined {
 	return typeof value === "string" && value ? value : undefined;
@@ -14,6 +14,11 @@ function errorCode(error: unknown): string | undefined {
 		: undefined;
 }
 
+function isAccessDenied(error: unknown): boolean {
+	const code = errorCode(error);
+	return code === "EPERM" || code === "EACCES";
+}
+
 function errorMessage(error: unknown): string {
 	return error instanceof Error ? error.message : String(error);
 }
@@ -39,6 +44,7 @@ export function toWaitCompletion(data: Record<string, unknown>, runId: string):
 			const childRunId = asNonEmptyString(child.runId);
 			const error = asNonEmptyString(child.error);
 			const model = asNonEmptyString(child.model);
+			const contextOverflow = child.contextOverflow === true;
 			return [{
 				...(agent ? { agent } : {}),
 				...(childRunId ? { runId: childRunId } : {}),
@@ -46,6 +52,7 @@ export function toWaitCompletion(data: Record<string, unknown>, runId: string):
 				...(outputState ? { outputState } : {}),
 				...(error ? { error } : {}),
 				...(model ? { model } : {}),
+				...(contextOverflow ? { contextOverflow: true } : {}),
 				...(artifactPaths ? { artifactPaths } : {}),
 			}];
 		})
@@ -115,9 +122,21 @@ export function collectWaitCompletions(terminal: AsyncRunSummary[], state: Subag
 			continue;
 		}
 		const publicResultPath = resultFilePath(resultsDir, run.id);
-		const resultPath = run.sessionId
-			? resultPayloadPathForSessionRun(resultsDir, run.sessionId, run.id) ?? publicResultPath
-			: publicResultPath;
+		let resultPath = publicResultPath;
+		try {
+			resultPath = run.sessionId
+				? resultPayloadPathForSessionRun(resultsDir, run.sessionId, run.id) ?? publicResultPath
+				: publicResultPath;
+		} catch (error) {
+			if (!isAccessDenied(error) || !run.sessionId) throw error;
+			try {
+				resultPath = fallbackResultPayloadPathForSessionRun(resultsDir, run.sessionId, run.id) ?? publicResultPath;
+			} catch (fallbackError) {
+				throw new Error(`Failed to read subagent result '${publicResultPath}': ${errorMessage(fallbackError)}`, {
+					cause: fallbackError instanceof Error ? fallbackError : undefined,
+				});
+			}
+		}
 		try {
 			const raw = JSON.parse(fs.readFileSync(resultPath, "utf-8")) as Record<string, unknown>;
 			completions.push(toWaitCompletion(raw, run.id));

package/dist/extensions/pi-subagents/src/runs/background/wait-subscriptions.ts

@@ -21,6 +21,20 @@ import {
 
 const SUBSCRIPTION_VERSION = 1;
 const RECONCILE_INTERVAL_MS = 1_000;
+/**
+ * How often the subscriptions directory is re-scanned for expired records left
+ * by other sessions. Rare compared to RECONCILE_INTERVAL_MS because it costs a
+ * directory read, and nothing depends on the sweep being prompt.
+ */
+const FOREIGN_SWEEP_INTERVAL_MS = 60_000;
+/**
+ * How far past expiry a record armed by another session is kept before it is
+ * swept. The owning session settles its own expired records with a "timed out"
+ * notice on the next restore(), so removing one the moment it expires would take
+ * that notice away from a session that simply had not resumed yet. A day is long
+ * enough for an ordinary return and short enough to bound the directory.
+ */
+const FOREIGN_SWEEP_GRACE_MS = 24 * 60 * 60 * 1000;
 
 export interface ArmWaitSubscriptionInput {
 	targetKind: "async" | "foreground";
@@ -95,6 +109,63 @@ export function createWaitSubscriptionManager(
 	state.waitSubscriptions = subscriptions;
 	const unresolvedRestoredForegroundTokens = new Set<string>();
 	let disposed = false;
+	let lastForeignSweepAt = 0;
+
+	/**
+	 * Remove expired records armed by another session.
+	 *
+	 * Only the owning session can be woken, so restore() never loads a foreign
+	 * record into `subscriptions` and reconcileRecord() returns before its
+	 * timeout branch. Nothing reconciles such a record and nothing expires it, so
+	 * a session that arms a wait and never comes back (forked, renamed, deleted)
+	 * leaves one file here per wait, forever.
+	 *
+	 * Kept for FOREIGN_SWEEP_GRACE_MS past expiry so an owner that resumes late
+	 * still finds its record and gets the timeout notice.
+	 *
+	 * Runs on the reconcile timer as well as at restore(), because a record that
+	 * is still live when another session starts would otherwise never be looked
+	 * at again: restore() only fires on session_start, and reconcile() walks the
+	 * in-memory map, which holds current-session records only. A host that keeps
+	 * one session open for hours is exactly where that gap bites.
+	 *
+	 * Never throws: it runs from the reconcile timer.
+	 */
+	const sweepExpiredForeignSubscriptions = (force = false) => {
+		const sweptAt = now();
+		if (!force && sweptAt - lastForeignSweepAt < FOREIGN_SWEEP_INTERVAL_MS) return;
+		lastForeignSweepAt = sweptAt;
+		let files: string[];
+		try {
+			files = fs.readdirSync(subscriptionsDir).filter((file) => file.endsWith(".json"));
+		} catch (error) {
+			if (!isNotFound(error)) console.error(`Failed to scan wait subscriptions in '${subscriptionsDir}':`, error);
+			return;
+		}
+		for (const file of files) {
+			const filePath = path.join(subscriptionsDir, file);
+			let record: WaitSubscriptionRecord | undefined;
+			try {
+				record = parseRecord(JSON.parse(fs.readFileSync(filePath, "utf-8")));
+			} catch (error) {
+				console.error(`Ignoring invalid wait subscription '${filePath}':`, error);
+				continue;
+			}
+			if (!record || file !== `${record.token}.json`) continue;
+			// The owning session keeps its own expired records so reconcileRecord()
+			// can still settle them with the "timed out" notice callers expect.
+			if (record.sessionId === state.currentSessionId) continue;
+			if (sweptAt < record.expiresAt + FOREIGN_SWEEP_GRACE_MS) continue;
+			try {
+				fs.unlinkSync(filePath);
+			} catch (error) {
+				// Losing this race is harmless: another session may have swept the
+				// same expired record. Anything else is reported and retried on the
+				// next sweep rather than interrupting the caller.
+				if (!isNotFound(error)) console.error(`Failed to remove expired wait subscription '${filePath}':`, error);
+			}
+		}
+	};
 
 	const remove = (record: WaitSubscriptionRecord) => {
 		try {
@@ -146,7 +217,7 @@ export function createWaitSubscriptionManager(
 				return;
 			}
 			const detached = run.children.filter((child) => child.status === "detached");
-			if (detached.some((child) => child.activityState === "needs_attention")) {
+			if (detached.some((child) => child.activityState === "needs_attention" && child.currentTool === "contact_supervisor")) {
 				settle(record, "needs attention", "Reply to the pending supervisor request or inspect the run status.");
 				return;
 			}
@@ -160,6 +231,7 @@ export function createWaitSubscriptionManager(
 		const runs = listAsyncRuns(asyncDirRoot, {
 			sessionId: record.sessionId,
 			runId: record.runId,
+			exactRunId: true,
 			resultsDir,
 			kill: options.kill,
 			now,
@@ -187,7 +259,11 @@ export function createWaitSubscriptionManager(
 	};
 
 	const reconcile = () => {
-		if (disposed || !state.currentSessionId) return;
+		if (disposed) return;
+		// Before the session check: with no current session every record is
+		// foreign, and expired ones should still be cleaned up.
+		sweepExpiredForeignSubscriptions();
+		if (!state.currentSessionId) return;
 		for (const record of [...subscriptions.values()]) {
 			try {
 				reconcileRecord(record);
@@ -233,6 +309,9 @@ export function createWaitSubscriptionManager(
 		restore() {
 			subscriptions.clear();
 			unresolvedRestoredForegroundTokens.clear();
+			// Unconditional: a process that starts without a session identity should
+			// still clear records nobody can act on.
+			sweepExpiredForeignSubscriptions(true);
 			if (!state.currentSessionId) return;
 			let files: string[];
 			try {
@@ -245,8 +324,7 @@ export function createWaitSubscriptionManager(
 				try {
 					const record = parseRecord(JSON.parse(fs.readFileSync(path.join(subscriptionsDir, file), "utf-8")));
 					if (!record || file !== `${record.token}.json`) continue;
-					const acceptedSessions = new Set(state.sessionLineage?.length ? state.sessionLineage : [state.currentSessionId]);
-					if (acceptedSessions.has(record.sessionId)) {
+					if (record.sessionId === state.currentSessionId) {
 						subscriptions.set(record.token, record);
 						if (record.targetKind === "foreground" && !state.foregroundRuns?.has(record.runId)) unresolvedRestoredForegroundTokens.add(record.token);
 					}

package/dist/extensions/pi-subagents/src/runs/background/wait-tool.ts

@@ -3,6 +3,7 @@ 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";
+import { finalizeToolResult } from "../../extension/tool-result.ts";
 
 export function registerWaitTool(pi: ExtensionAPI, state: SubagentState, enabled = resolveWaitToolConfig().enabled, subscriptions?: Pick<WaitSubscriptionManager, "arm">): void {
 	const tool: ToolDefinition<typeof SubagentWaitParams, Details> = {
@@ -16,18 +17,19 @@ In an interactive chat, do not call this merely to wait: return control to the u
 • { 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.
+• { stopOnAttention: false } — for blocking waits only, keep waiting through idle or long-thinking attention; supervisor/contact requests still stop the wait.
 • { timeoutMs: 600000 } — stop waiting after N ms; active work keeps running.
 
 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 SELESAI_SUBAGENT_WAIT_TOOL_ENABLED and returns immediately without blocking."}`,
 		parameters: SubagentWaitParams,
-		execute(_id, params, signal, onUpdate, ctx) {
-			return waitForSubagents(params, signal, {
+		async execute(_id, params, signal, onUpdate, ctx) {
+			return finalizeToolResult(await waitForSubagents(params, signal, {
 				state,
 				events: pi.events,
 				enabled,
 				onUpdate,
 				...(subscriptions && ctx?.hasUI ? { subscribe: (input) => subscriptions.arm(input) } : {}),
-			});
+			}));
 		},
 	};
 	pi.registerTool(tool);

package/dist/extensions/pi-subagents/src/runs/foreground/async-steering-action.ts

@@ -8,7 +8,17 @@ import { readStatus } from "../../shared/utils.ts";
 import { consumeSteerAcks, deliverInterruptRequest, queueRevivalBrief, requestAsyncSteer, type SteerDeliveryMode, type SteerRequest } from "../background/control-channel.ts";
 import { resolveAsyncResumeTarget } from "../background/async-resume.ts";
 import { reconcileAsyncRun } from "../background/stale-run-reconciler.ts";
-import { actionResultFromSteeringStatus, claimSteeringRecovery, createSteeringStatus, recordSteeringRequest, remainingSteeringRecoveryLimits, updateSteeringTarget, waitForSteeringAction } from "../background/steering.ts";
+import { actionResultFromSteeringStatus, claimSteeringRecovery, createSteeringStatus, recordSteeringRequest, remainingSteeringRecoveryLimits, steeringReceipt, updateSteeringTarget, waitForSteeringAction } from "../background/steering.ts";
+
+export function canQueueRetainedAsyncFollowUp(status: AsyncStatus, index?: number): boolean {
+	const steps = status.steps ?? [];
+	return status.state === "complete"
+		&& Boolean(status.parentWorkflowRunId)
+		&& steps.length === 1
+		&& (steps[0]?.status === "complete" || steps[0]?.status === "completed")
+		&& Boolean(steps[0]?.sessionFile ?? status.sessionFile)
+		&& (index === undefined || index === 0);
+}
 
 export async function steerAsyncRun(input: {
 	state: SubagentState;
@@ -51,7 +61,7 @@ export async function steerAsyncRun(input: {
 	}
 	const steps = status.steps ?? [];
 	if (status.state !== "running" && status.state !== "queued") {
-		const retained = input.mode === "follow_up" && status.state === "complete" && Boolean(status.parentWorkflowRunId) && steps.length === 1 && (steps[0]?.status === "complete" || steps[0]?.status === "completed") && Boolean(steps[0]?.sessionFile ?? status.sessionFile);
+		const retained = input.mode === "follow_up" && canQueueRetainedAsyncFollowUp(status, input.index);
 		if (!retained) {
 			return {
 				content: [{ type: "text", text: `Async run '${input.runId}' is not running or queued and cannot be steered.` }],
@@ -59,9 +69,6 @@ export async function steerAsyncRun(input: {
 				details: { mode: "management", results: [] },
 			};
 		}
-		if (input.index !== undefined && input.index !== 0) {
-			return { content: [{ type: "text", text: `Retained async run '${status.runId}' has one child. Index ${input.index} is out of range.` }], isError: true, details: { mode: "management", results: [] } };
-		}
 		const request: SteerRequest = { type: "steer", id: randomUUID(), ts: Date.now(), message: input.message.trim(), mode: "follow_up", targetIndex: 0, source: "steer-action" };
 		try {
 			queueRevivalBrief(asyncDir, request);
@@ -72,7 +79,7 @@ export async function steerAsyncRun(input: {
 		recordSteeringRequest(status.steering, { id: request.id, requestedAt: request.ts, source: request.source, message: request.message, targets: [{ index: 0, state: "scheduled" }] });
 		writeAtomicJson(path.join(asyncDir, "status.json"), status);
 		const queued = { requestId: request.id, state: "scheduled" as const, deliveryStatus: "queued" as const, sourceRunId: status.runId, targets: [{ index: 0, state: "scheduled" as const }] };
-		return { content: [{ type: "text", text: `Follow-up queued for the next resume of retained async run ${status.runId} (request ${request.id}).` }], details: { mode: "management", results: [], steering: queued } };
+		return { content: [{ type: "text", text: steeringReceipt(request.message, `Follow-up queued for the next resume of retained async run ${status.runId} (request ${request.id}).`) }], details: { mode: "management", results: [], steering: queued } };
 	}
 	if (input.index !== undefined) {
 		if (input.index < 0 || input.index >= steps.length) {
@@ -135,17 +142,17 @@ export async function steerAsyncRun(input: {
 	const targets = targetIndexes.map((index) => ({ index, state: status.steps?.[index]?.status === "pending" ? "scheduled" as const : "pending" as const }));
 	if (targets.every((target) => target.state === "scheduled")) {
 		const scheduled = { requestId, state: "scheduled" as const, deliveryStatus: "queued" as const, sourceRunId: status.runId, targets };
-		return { content: [{ type: "text", text: `Steering scheduled for async run ${status.runId} (request ${requestId}).` }], details: { mode: "management", results: [], steering: scheduled } };
+		return { content: [{ type: "text", text: steeringReceipt(input.message, `Steering scheduled for async run ${status.runId} (request ${requestId}).`) }], details: { mode: "management", results: [], steering: scheduled } };
 	}
 	const waited = await waitForSteeringAction({ asyncDir, sourceRunId: status.runId, requestId, timeoutMs: input.ackTimeoutMs ?? 3_000, signal: input.signal });
 	const result = waited ?? { requestId, state: "pending" as const, deliveryStatus: "queued" as const, sourceRunId: status.runId, targets };
 	if (input.signal?.aborted) {
-		return { content: [{ type: "text", text: `Steering pending for async run ${status.runId} (request ${requestId}); caller aborted before recovery.` }], details: { mode: "management", results: [], steering: result } };
+		return { content: [{ type: "text", text: steeringReceipt(input.message, `Steering pending for async run ${status.runId} (request ${requestId}); caller aborted before recovery.`) }], details: { mode: "management", results: [], steering: result } };
 	}
 	const finalStatus = readStatus(asyncDir);
 	const finalResult = finalStatus?.steering ? actionResultFromSteeringStatus(finalStatus.steering, status.runId, requestId) : undefined;
 	if (finalResult?.state === "delivered") {
-		return { content: [{ type: "text", text: `Steering delivered for async run ${status.runId} (request ${requestId}).` }], details: { mode: "management", results: [], steering: finalResult } };
+		return { content: [{ type: "text", text: steeringReceipt(input.message, `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 recoveryAllowed = (input.mode ?? "steer") === "steer" && status.mode === "single" && status.isNested !== true && running.length === 1 && Boolean(finalStatus?.steering) && (input.index === undefined || input.index === 0);
@@ -160,7 +167,7 @@ export async function steerAsyncRun(input: {
 		try {
 			const latest = readStatus(asyncDir);
 			const latestResult = latest?.steering ? actionResultFromSteeringStatus(latest.steering, status.runId, requestId) : undefined;
-			if (latestResult?.state === "delivered") return { content: [{ type: "text", text: `Steering delivered for async run ${status.runId} (request ${requestId}).` }], details: { mode: "management", results: [], steering: latestResult } };
+			if (latestResult?.state === "delivered") return { content: [{ type: "text", text: steeringReceipt(input.message, `Steering delivered for async run ${status.runId} (request ${requestId}).`) }], details: { mode: "management", results: [], steering: latestResult } };
 			const committedAt = Date.now();
 			input.onBeforeRecoveryClaim?.(requestId, committedAt);
 			const { claimPath, markerPath } = claimSteeringRecovery(asyncDir, { requestId, sourceRunId: status.runId, committedAt });
@@ -170,7 +177,7 @@ export async function steerAsyncRun(input: {
 			if (preCommitResult?.state === "delivered" && preCommitResult.targets.every((target) => target.deliveredAt !== undefined && target.deliveredAt <= committedAt)) {
 				fs.rmSync(markerPath, { force: true });
 				fs.rmSync(claimPath, { force: true });
-				return { content: [{ type: "text", text: `Steering delivered for async run ${status.runId} (request ${requestId}).` }], details: { mode: "management", results: [], steering: preCommitResult } };
+				return { content: [{ type: "text", text: steeringReceipt(input.message, `Steering delivered for async run ${status.runId} (request ${requestId}).`) }], details: { mode: "management", results: [], steering: preCommitResult } };
 			}
 			try {
 				deliverInterruptRequest({ asyncDir, source: "steering-recovery" });
@@ -228,7 +235,7 @@ export async function steerAsyncRun(input: {
 			}
 			const recovered = paused.steering ? actionResultFromSteeringStatus(paused.steering, status.runId, requestId, revived.details.asyncId) : undefined;
 			appendSteeringNotice("recovered", `Steering recovered for run ${status.runId}; replacement ${revived.details.asyncId} launched.`);
-			return { content: [{ type: "text", text: `Steering recovered for async run ${status.runId}; replacement ${revived.details.asyncId} launched after the source paused.` }], details: { mode: "management", results: [], steering: recovered ?? { requestId, state: "recovered", sourceRunId: status.runId, replacementRunId: revived.details.asyncId, deliveryStatus: "delivered", targets: [{ index: input.index ?? 0, state: "recovered" }] } } };
+			return { content: [{ type: "text", text: steeringReceipt(input.message, `Steering recovered for async run ${status.runId}; replacement ${revived.details.asyncId} launched after the source paused.`) }], details: { mode: "management", results: [], steering: recovered ?? { requestId, state: "recovered", sourceRunId: status.runId, replacementRunId: revived.details.asyncId, deliveryStatus: "delivered", targets: [{ index: input.index ?? 0, state: "recovered" }] } } };
 		} catch (error) {
 			const reason = error instanceof Error ? error.message : String(error);
 			const failedStatus = readStatus(asyncDir);
@@ -242,13 +249,13 @@ export async function steerAsyncRun(input: {
 			}
 			const failed = failedStatus?.steering ? actionResultFromSteeringStatus(failedStatus.steering, status.runId, requestId) : undefined;
 			appendSteeringNotice("failed", `Steering failed for run ${status.runId}: ${reason}`);
-			return { content: [{ type: "text", text: `Steering failed for async run ${status.runId} (request ${requestId}): ${reason}` }], isError: true, details: { mode: "management", results: [], steering: failed ?? { requestId, state: "failed", sourceRunId: status.runId, deliveryStatus: "queued", targets: [{ index: input.index ?? 0, state: "failed", reason }] } } };
+			return { content: [{ type: "text", text: steeringReceipt(input.message, `Steering failed for async run ${status.runId} (request ${requestId}): ${reason}`) }], isError: true, details: { mode: "management", results: [], steering: failed ?? { requestId, state: "failed", sourceRunId: status.runId, deliveryStatus: "queued", targets: [{ index: input.index ?? 0, state: "failed", reason }] } } };
 		}
 	}
 	const stateText = result.state === "failed" ? "failed" : result.state === "partial" ? "partial" : result.deliveryStatus === "queued" ? "queued" : result.state === "delivered" ? "delivered" : result.state === "scheduled" ? "scheduled" : result.state === "recovered" ? "recovered" : "pending";
 	const isError = result.state === "failed" || result.state === "partial";
 	return {
-		content: [{ type: "text", text: `Steering ${stateText} for async run ${status.runId} (request ${requestId}).` }],
+		content: [{ type: "text", text: steeringReceipt(input.message, `Steering ${stateText} for async run ${status.runId} (request ${requestId}).`) }],
 		...(isError ? { isError: true } : {}),
 		details: { mode: "management", results: [], steering: result },
 	};

package/dist/extensions/pi-subagents/src/runs/foreground/async-stop-action.ts

@@ -3,6 +3,7 @@ import type { AgentToolResult } from "@earendil-works/pi-agent-core";
 import type { Details, SubagentState } from "../../shared/types.ts";
 import { deliverStopRequest } from "../background/control-channel.ts";
 import { reconcileAsyncRun } from "../background/stale-run-reconciler.ts";
+import { isStoppableAsyncStatusStep, resolveAsyncStatusChild, type ResolvedAsyncStatusChild } from "../shared/child-identity.ts";
 
 function getAsyncStopTarget(
 	state: SubagentState,
@@ -25,6 +26,7 @@ export function stopAsyncRun(
 	runId: string | undefined,
 	kill?: (pid: number, signal?: NodeJS.Signals | 0) => boolean,
 	location?: { asyncDir: string | null; resolvedId?: string },
+	childId?: string,
 ): AgentToolResult<Details> | null {
 	const target = getAsyncStopTarget(state, runId, location);
 	if (!target) return null;
@@ -43,15 +45,34 @@ export function stopAsyncRun(
 			details: { mode: "management", results: [] },
 		};
 	}
+	let child: ResolvedAsyncStatusChild | undefined;
+	if (childId !== undefined) {
+		const resolution = resolveAsyncStatusChild(status, childId);
+		if (!resolution.ok) {
+			return {
+				content: [{ type: "text", text: resolution.message }],
+				isError: true,
+				details: { mode: "management", results: [] },
+			};
+		}
+		child = resolution.child;
+		if (!isStoppableAsyncStatusStep(child.step)) {
+			return {
+				content: [{ type: "text", text: `Child '${childId}' in async run '${status.runId}' is ${child.step.status}; stop only supports pending or running children.` }],
+				isError: true,
+				details: { mode: "management", results: [] },
+			};
+		}
+	}
 	try {
-		deliverStopRequest({ asyncDir: target.asyncDir, pid: typeof status.pid === "number" ? status.pid : undefined, kill, source: "stop-action" });
+		deliverStopRequest({ asyncDir: target.asyncDir, pid: typeof status.pid === "number" ? status.pid : undefined, kill, source: "stop-action", targetIndex: child?.index, childId: child?.id ?? childId });
 		const tracked = state.asyncJobs.get(target.asyncId);
 		if (tracked) {
 			tracked.activityState = undefined;
 			tracked.updatedAt = Date.now();
 		}
 		return {
-			content: [{ type: "text", text: `Stop requested for async run ${target.asyncId}.` }],
+			content: [{ type: "text", text: child ? `Stop requested for child ${child.id} in async run ${target.asyncId}.` : `Stop requested for async run ${target.asyncId}.` }],
 			details: { mode: "management", results: [] },
 		};
 	} catch (error) {