gentle-pi 2.4.0 → 2.6.0

package/lib/agents-runner.ts

@@ -0,0 +1,1012 @@
+import { createHash } from "node:crypto";
+import type { Duplex, Readable, Writable } from "node:stream";
+import { RESEARCH_SELECTION_ENV, RESEARCH_ARTIFACT_ENV, type ResearchArtifactIntent } from "./sdd-research-capabilities.ts";
+import { AGENT_MODE, formatModelRef, type AgentDefinition, type AgentMode, type ModelRef } from "./agents-config.ts";
+import { CHILD_QUERY_MAX_INFLIGHT, CHILD_QUERY_TIMEOUT_MS, parseChildFrame, validChildMessage, validChildQueryId } from "./agents-messaging.ts";
+import { ParentStandingReviewPermissionBroker } from "./review-session-standing-permission-ipc.ts";
+import { isFinished, normalizeRpcEvent, TASK_EVENT, TASK_STATUS, taskLabel, type AskRequest, type ChildResponseObservation, type TaskRecord, type RemediationTaskState, type TaskStore } from "./agents-protocol.ts";
+
+// Gentle Agents runner. Every subagent is its own `pi --mode rpc` process:
+// the host never runs subagent work on the TUI thread. It writes JSON
+// commands, reads JSON lines, applies deltas to the store, answers dialogs,
+// and enforces an inactivity watchdog per task.
+
+export interface ChildLike {
+	pid: number | undefined;
+	stdin: Writable;
+	stdout: Readable;
+	stderr: Readable | null | undefined;
+	stdio?: Array<Duplex | null | undefined>;
+	kill(signal?: NodeJS.Signals): boolean;
+	send?(message: Record<string, unknown>, callback?: (error: Error | null) => void): boolean;
+	disconnect?(): void;
+	channel?: { unref?(): void };
+	on(event: "exit", listener: (code: number | null, signal: NodeJS.Signals | null) => void): unknown;
+	on(event: "error", listener: (error: Error) => void): unknown;
+	on(event: "spawn" | "message" | "disconnect", listener: (...args: unknown[]) => void): unknown;
+}
+
+export interface SpawnOptions {
+	cwd: string;
+	env: NodeJS.ProcessEnv;
+	detached?: boolean;
+	stdio?: Array<"pipe" | "ignore" | "inherit" | "ipc">;
+}
+
+export type Spawn = (command: string, args: string[], options: SpawnOptions) => ChildLike;
+
+export interface ProcessControl {
+	platform: NodeJS.Platform;
+	kill(pid: number, signal: NodeJS.Signals | 0): void;
+}
+
+export interface PiCommand {
+	command: string;
+	args: string[];
+}
+
+export interface RunnerDeps {
+	spawn: Spawn;
+	now(): number;
+	schedule(fn: () => void, ms: number): () => void;
+	pi: PiCommand;
+	process?: ProcessControl;
+}
+
+export interface RunnerLimits {
+	maxConcurrency: number;
+	stallTimeoutMs: number;
+}
+
+export interface AskAnswer {
+	value?: string;
+	confirmed?: boolean;
+	cancelled?: boolean;
+}
+
+export interface TaskQuery {
+	taskId: string;
+	requestId: string;
+}
+
+export const MAX_CHILD_RESPONSE_OBSERVATIONS = 128;
+
+/** Local producer snapshot only; never native workflow success or export authority.
+ * Scope excludes tools, compaction, hidden provider retries and history replay.
+ * Each message_end is retained separately; RPC supplies no stable dedupe key.
+ * Unsettled shutdown may lose in-flight responses even when droppedResponses is 0.
+ */
+export interface ChildObservationSnapshot {
+	readonly coverage: "final_assistant_messages_only";
+	readonly agentSettled: boolean;
+	readonly responses: readonly ChildResponseObservation[];
+	readonly droppedResponses: number;
+}
+interface ChildObservationBuffer {
+	agentSettled: boolean;
+	responses: ChildResponseObservation[];
+	droppedResponses: number;
+}
+
+export interface RunnerHooks {
+	askUser(taskId: string, request: AskRequest, raw: Record<string, unknown>): Promise<AskAnswer>;
+	/** Optional immutable snapshot, delivered once at existing finalization.
+	 * Undefined when collection was disabled or no child handle was created.
+	 * Parent must check task.status AND agentSettled; observations are not success.
+	 */
+	onFinish?(task: TaskRecord, observations?: ChildObservationSnapshot): void;
+	// Accepts a child notification only while the originating parent session is active.
+	onNotification?(task: TaskRecord, message: string): boolean | void;
+	onQuery?(task: TaskRecord, requestId: string, message: string): boolean | void;
+	// Parent-only observation of a paired successful filesystem tool, not prose.
+	onSuccessfulMutation?(task: TaskRecord, tool: { toolName: "write" | "edit"; toolCallId: string; path: string }): void | Promise<void>;
+}
+
+export interface RemediationHarnessPlan { command?: string; naReason?: string }
+export interface RemediationRollbackPlan { boundary: string; command: string }
+export interface RemediationScope { cwd: string; editPaths: string[]; commands: string[]; allowedEditRoots: string[] }
+export interface RemediationPlan {
+	editPaths?: string[];
+	cwd: string;
+	commands: string[];
+	runtimeHarness: RemediationHarnessPlan;
+	rollback: RemediationRollbackPlan;
+}
+export interface RemediationObservation {
+	slot: number;
+	toolCallId: string;
+	command: string;
+	cwd: string;
+	exitCode: number | null;
+	result: string;
+}
+export interface RemediationObservations {
+	failedEvidenceRevision: string;
+	plan: RemediationPlan;
+	observations: RemediationObservation[];
+	pending: Record<string, number>;
+	invalid: boolean;
+}
+const concrete = (value: unknown): value is string => typeof value === "string" && value.trim() === value && value.length > 3 && value.length <= 4096 && !/[\0\r\n]/.test(value);
+export function parseRemediationPlan(value: unknown, cwd: string): RemediationPlan {
+	const plan = value as RemediationPlan;
+	if (!plan || plan.cwd !== cwd || !Array.isArray(plan.commands) || plan.commands.length < 1 || plan.commands.length > 16 || !plan.commands.every(concrete) ||
+		!concrete(plan.rollback?.boundary) || !concrete(plan.rollback?.command) || !plan.runtimeHarness ||
+		!(concrete(plan.runtimeHarness.command) && plan.runtimeHarness.naReason === undefined || plan.runtimeHarness.command === undefined && concrete(plan.runtimeHarness.naReason) && plan.runtimeHarness.naReason.length >= 20 && /because/i.test(plan.runtimeHarness.naReason))) throw new TypeError("Invalid remediation evidence plan");
+	return structuredClone(plan);
+}
+export const plannedCommands = (plan: RemediationPlan) => [...plan.commands, ...(plan.runtimeHarness.command ? [plan.runtimeHarness.command] : []), plan.rollback.command];
+const evidenceDigest = (value: string) => `sha256:${createHash("sha256").update(value).digest("hex")}`;
+
+// Only paired stock-shell observations may fill this remediation-only plan.
+export function observeRemediationTool(state: RemediationObservations, raw: Record<string, unknown>): void {
+	if (raw.toolName !== "bash" || typeof raw.toolCallId !== "string") return;
+	const id = raw.toolCallId;
+	if (raw.type === "tool_execution_start") {
+		const command = (raw.args as { command?: unknown } | undefined)?.command;
+		if (typeof command !== "string" || !plannedCommands(state.plan).includes(command)) return;
+		if (Object.hasOwn(state.pending, id) || state.observations.some(item => item.toolCallId === id) || Object.keys(state.pending).length >= 32) { state.invalid = true; return; }
+		const slot = plannedCommands(state.plan).findIndex((item, index) => item === command && !state.observations.some(observation => observation.slot === index) && !Object.values(state.pending).includes(index));
+		if (slot < 0) { state.invalid = true; return; }
+		state.pending[id] = slot;
+	}
+	if (raw.type !== "tool_execution_end" || !Object.hasOwn(state.pending, id)) return;
+	const slot = state.pending[id];
+	const command = plannedCommands(state.plan)[slot];
+	delete state.pending[id];
+	const result = raw.result as { content?: unknown; details?: { truncation?: unknown; fullOutputPath?: unknown; remediationCommand?: RemediationObservation & { truncated?: boolean } } } | undefined;
+	const observed = result?.details?.remediationCommand;
+	const output = JSON.stringify(result?.content ?? null);
+	if (!observed || observed.toolCallId !== id || observed.command !== command || observed.cwd !== state.plan.cwd ||
+		!(observed.exitCode === null || Number.isInteger(observed.exitCode)) || state.observations.length >= 32) { state.invalid = true; return; }
+	const contentValid = Array.isArray(result?.content) && result.content.length > 0 && result.content.every(part =>
+		part && typeof part === "object" && (part as { type?: unknown }).type === "text" && typeof (part as { text?: unknown }).text === "string");
+	if (raw.isError !== false || observed.exitCode !== 0 || observed.truncated || result?.details?.truncation || result?.details?.fullOutputPath || output.length > 16_000 || !contentValid) state.invalid = true;
+	state.observations.push({ slot, toolCallId: id, command, cwd: observed.cwd, exitCode: observed.exitCode, result: `Observed command output ${evidenceDigest(output)}: ${output.slice(0, 400)}` });
+}
+export function remediationEvidence(state: RemediationObservations) {
+	const find = (slot: number) => state.observations.find(item => item.slot === slot && item.command === plannedCommands(state.plan)[slot] && item.cwd === state.plan.cwd && item.exitCode === 0);
+	if (state.invalid || Object.keys(state.pending).length || !/^sha256:[0-9a-f]{64}$/.test(state.failedEvidenceRevision) || !plannedCommands(state.plan).every((_, slot) => find(slot))) return undefined;
+	const result = (slot: number) => `cwd ${state.plan.cwd}; retained command observation ${evidenceDigest(JSON.stringify(find(slot)))}`;
+	return {
+		schema: "gentle-ai.remediation-evidence/v1",
+		failed_evidence_revision: state.failedEvidenceRevision,
+		commands: state.plan.commands.map((command, slot) => ({ command, exit_code: 0, result: result(slot) })),
+		runtime_harness: state.plan.runtimeHarness.command ? { status: "passed", command: state.plan.runtimeHarness.command, result: result(state.plan.commands.length) } : { status: "not_applicable", na_reason: state.plan.runtimeHarness.naReason },
+		rollback: { boundary: state.plan.rollback.boundary, evidence: result(plannedCommands(state.plan).length - 1) },
+	};
+}
+
+export interface SddChangeSelection {
+	changeName: string;
+	workspaceRoot: string;
+	phase: "apply" | "verify" | "sync" | "archive" | "remediate";
+	failedEvidenceRevision?: string;
+}
+
+export const SDD_CHANGE_FLAG = "--gentle-sdd-change";
+
+export interface RemediationTerminalFacts { spawned: boolean; exited: boolean; cleanupConfirmed: boolean }
+
+export const REMEDIATION_PLAN_ENV = "GENTLE_PI_SDD_REMEDIATION_PLAN";
+
+export interface TaskRequest {
+	remediationIntent?: unknown;
+	sddRemediation?: RemediationTaskState;
+	sddPreflightContext?: string;
+	finalizeRemediation?: (task: TaskRecord, facts: RemediationTerminalFacts) => Promise<void>;
+	agent: AgentDefinition;
+	prompt: string;
+	label: string | undefined;
+	context: string | undefined;
+	mode: AgentMode;
+	cwd: string;
+	parentSessionId: string;
+	model: ModelRef | undefined;
+	thinking: string | undefined;
+	sessionDir: string;
+	resumeSessionPath: string | undefined;
+	env: NodeJS.ProcessEnv;
+	// A launch-local SDD identity. It is never prompt text or shared state.
+	sddChange?: SddChangeSelection;
+	// Untrusted narrowing intent; paths come only from matching host provenance.
+	researchSelection?: unknown;
+	researchArtifact?: ResearchArtifactIntent;
+	extensionPaths?: string[];
+	// Captures the originating session; invoked only after successful OS spawn.
+	onLaunch?: () => void;
+	/** Default off. Parent owns policy before opting into bounded local buffering,
+	 * and must recheck policy/catalog privacy before recording or forwarding.
+	 * This flag does not authorize telemetry export or perform policy subprocesses.
+	 */
+	collectResponseObservations?: boolean;
+	/** Optional parallel preparation after dequeue; never delays OS spawn.
+	 * Unready at the first observation checkpoint permanently drops collection. */
+	prepareResponseObservations?: () => Promise<boolean>;
+	/** Optional synchronous parent-local grant check; never perform I/O here.
+	 * Parent checks environment, known revocation and a monotonic expiry against
+	 * its fresh native policy grant. False/throw permanently discards this task's
+	 * buffer. Checked once ready, on RPC values, and finish; this is not a watcher.
+	 * Omission preserves the explicit opt-in producer API, not policy authority.
+	 */
+	canCollectResponseObservations?: () => boolean;
+	// This closure stays only in the parent process. Its presence creates an
+	// inherited fd, never an environment boolean or model-visible permission.
+	authorizeParentStandingReviewPermission?: (repositoryIdentity: string) => boolean;
+}
+
+interface ProcessLike {
+	execPath: string;
+	argv: string[];
+	env: NodeJS.ProcessEnv;
+}
+
+interface Pending {
+	resolve(value: Record<string, unknown>): void;
+}
+
+interface PendingQuery {
+	cancel: () => void;
+	replying: boolean;
+}
+
+interface PendingReply {
+	resolve(value: boolean): void;
+}
+
+interface LiveTask {
+	child: ChildLike;
+	observations?: ChildObservationBuffer;
+	observationGuard?: () => boolean;
+	observationPreparation?: () => boolean;
+	pending: Map<string, Pending>;
+	queries: Map<string, PendingQuery>;
+	replies: Map<string, PendingReply>;
+	cancelStall: () => void;
+	cancelGrace: () => void;
+	processGroup: number | undefined;
+	terminal: { status: TaskRecord["status"]; error: string | null } | undefined;
+	childExit: number | null | undefined;
+	cleanupDeadlineAt: number | undefined;
+	quarantined: boolean;
+	nextId: number;
+	permissionBroker?: ParentStandingReviewPermissionBroker;
+	ipcClosed: boolean;
+	acknowledgedIpcIds: Set<string>;
+	acknowledgedIpcOrder: string[];
+	mutationStarts: Map<string, { toolName: "write" | "edit"; toolCallId: string; path: string }>;
+}
+
+const CHILD_MARKER = "GENTLE_PI_AGENTS_CHILD";
+const IPC_MARKER = "GENTLE_PI_AGENTS_OWNED_IPC";
+const PARENT_NOTIFICATION_TOOL = "subagent_parent_message";
+const DEFAULT_TOOLS: readonly string[] = [];
+const TERMINATION_GRACE_MS = 250;
+const GROUP_CONFIRM_MS = 25;
+const GROUP_CONFIRM_DEADLINE_MS = 1_000;
+const QUERY_REJECTION_ERRORS = new Set([
+	"invalid child IPC frame",
+	"invalid child IPC correlation",
+	"unsupported child IPC kind",
+	"invalid child IPC message",
+	"task is not a live owned recipient",
+	"task parent cannot accept queries",
+	"task parent is not the active host session",
+	"duplicate query request",
+	"too many pending parent queries",
+	"parent query timed out",
+	"parent rejected query",
+]);
+const QUERY_REJECTION = Symbol("query rejection");
+
+function rejectQuery(error: string): never {
+	throw { [QUERY_REJECTION]: error };
+}
+
+function queryRejection(error: unknown): string {
+	if (error && typeof error === "object" && QUERY_REJECTION in error) {
+		const value = (error as { [QUERY_REJECTION]?: unknown })[QUERY_REJECTION];
+		if (typeof value === "string" && QUERY_REJECTION_ERRORS.has(value)) return value;
+	}
+	return "parent rejected query";
+}
+
+const hostProcess: ProcessControl = { platform: process.platform, kill: (pid, signal) => process.kill(pid, signal) };
+
+export function childArguments(request: TaskRequest): string[] {
+	const args = ["--mode", "rpc", "--session-dir", request.sessionDir];
+	for (const path of request.extensionPaths ?? []) args.push("--extension", path);
+	if (request.sddChange) args.push(SDD_CHANGE_FLAG, JSON.stringify(request.sddChange));
+	if (request.resumeSessionPath) args.push("--session", request.resumeSessionPath);
+	if (request.model) args.push("--model", request.thinking ? `${formatModelRef(request.model)}:${request.thinking}` : formatModelRef(request.model));
+	else if (request.thinking) args.push("--thinking", request.thinking);
+	const tools = request.agent.tools.length > 0 ? [...new Set([...request.agent.tools, PARENT_NOTIFICATION_TOOL])] : DEFAULT_TOOLS;
+	if (tools.length > 0) args.push("--tools", tools.join(","));
+	if (request.agent.instructions.length > 0) args.push("--append-system-prompt", request.agent.instructions);
+	return args;
+}
+
+// The child is the same pi that is running us: node plus its cli entry.
+// GENTLE_PI_AGENTS_PI overrides it with a command line.
+export function piCommand(proc: ProcessLike = process): PiCommand {
+	const override = proc.env.GENTLE_PI_AGENTS_PI?.trim();
+	if (override) {
+		const [command, ...args] = override.split(/\s+/);
+		return { command, args };
+	}
+	const entry = proc.argv[1];
+	if (entry && /(^|[\\/])cli\.js$/.test(entry)) return { command: proc.execPath, args: [entry] };
+	return { command: "pi", args: [] };
+}
+
+// RPC framing is strict JSONL: LF only, optional CR. Lines that do not parse
+// are dropped (pi's own parse errors arrive as responses anyway).
+export class JsonLines {
+	private buffer = "";
+	private readonly onValue: (value: unknown) => void;
+
+	constructor(onValue: (value: unknown) => void) {
+		this.onValue = onValue;
+	}
+
+	push(chunk: string): void {
+		this.buffer += chunk;
+		const lines = this.buffer.split("\n");
+		this.buffer = lines.pop() ?? "";
+		for (const raw of lines) {
+			const line = raw.endsWith("\r") ? raw.slice(0, -1) : raw;
+			if (line.length === 0) continue;
+			try {
+				this.onValue(JSON.parse(line));
+			} catch {
+				// not JSON: ignore
+			}
+		}
+	}
+}
+
+export function promptText(request: TaskRequest): string {
+	const prompt = request.context ? `${request.prompt}\n\n## Context\n${request.context}` : request.prompt;
+	return request.sddRemediation ? `${prompt}\n\n## Host-owned remediation evidence plan\nExecute these exact commands in the selected cwd; do not perform native acquire or settle.\n${JSON.stringify(request.sddRemediation.plan)}\nFailed evidence: ${request.sddRemediation.failedEvidenceRevision}` : prompt;
+}
+
+export class AgentRunner {
+	private readonly store: TaskStore;
+	private readonly limits: RunnerLimits;
+	private readonly deps: RunnerDeps;
+	private readonly hooks: RunnerHooks;
+	private readonly processControl: ProcessControl;
+	private readonly queue: Array<{ task: TaskRecord; request: TaskRequest }> = [];
+	private readonly live = new Map<string, LiveTask>();
+	private readonly remediationFinalizers = new Map<string, NonNullable<TaskRequest["finalizeRemediation"]>>();
+	private readonly finalizingRemediation = new Set<string>();
+	private readonly waiters = new Map<string, Array<(task: TaskRecord) => void>>();
+	private readonly queryWaiters = new Map<string, Array<(query: TaskQuery | undefined) => void>>();
+	private readonly firstQueries = new Map<string, TaskQuery>();
+	private counter = 0;
+
+	constructor(store: TaskStore, limits: RunnerLimits, deps: RunnerDeps, hooks: RunnerHooks) {
+		this.store = store;
+		this.limits = limits;
+		this.deps = deps;
+		this.hooks = hooks;
+		this.processControl = deps.process ?? hostProcess;
+	}
+
+	prepareRemediation(request: TaskRequest): TaskRecord {
+		if (request.agent.name !== "sdd-remediate" || this.store.list().some(task => task.agent === "sdd-remediate" && task.cwd === request.cwd && !isFinished(task.status))) throw new Error("Remediation already preparing/running; reconcile its retained task before another actor");
+		return this.createTask(request);
+	}
+
+	private createTask(request: TaskRequest): TaskRecord {
+		const now = this.deps.now();
+		this.counter += 1;
+		const task: TaskRecord = {
+			id: `${now.toString(36)}-${this.counter.toString(36)}-${Math.random().toString(36).slice(2, 6)}`,
+			agent: request.agent.name,
+			...(request.sddRemediation ? { sddRemediation: structuredClone(request.sddRemediation) } : {}),
+			...(request.sddPreflightContext ? { sddPreflightContext: request.sddPreflightContext } : {}),
+			mode: request.mode,
+			prompt: request.prompt,
+			...(request.researchArtifact ? { researchArtifact: structuredClone(request.researchArtifact) } : {}),
+			label: taskLabel(request.prompt, request.label),
+			cwd: request.cwd,
+			parentSessionId: request.parentSessionId,
+			status: TASK_STATUS.QUEUED,
+			createdAt: now,
+			startedAt: null,
+			endedAt: null,
+			model: formatModelRef(request.model),
+			thinking: request.thinking,
+			sessionPath: request.resumeSessionPath ?? null,
+			error: null,
+			result: null,
+			lastStep: "queued",
+			lastActivityAt: now,
+			turns: 0,
+			toolCalls: 0,
+			tokens: 0,
+			cost: 0,
+		};
+		this.store.add(task);
+		return task;
+	}
+
+	run(request: TaskRequest, preparedRemediation?: TaskRecord): TaskRecord {
+		if (preparedRemediation && (this.store.get(preparedRemediation.id) !== preparedRemediation || preparedRemediation.cwd !== request.cwd || preparedRemediation.agent !== "sdd-remediate" || preparedRemediation.status !== TASK_STATUS.QUEUED || this.queue.some(entry => entry.task.id === preparedRemediation.id))) throw new Error("Invalid or already dispatched remediation task");
+		const task = preparedRemediation ?? this.createTask(request);
+		if (request.sddRemediation) task.sddRemediation = structuredClone(request.sddRemediation);
+		if (request.finalizeRemediation) this.remediationFinalizers.set(task.id, request.finalizeRemediation);
+		// A caller can retain and mutate its request after dispatch. Preserve only
+		// the identity selected at construction for this child launch.
+		const launchRequest = {
+			...request,
+			sddChange: request.sddChange && { ...request.sddChange },
+			researchArtifact: request.researchArtifact && structuredClone(request.researchArtifact),
+		};
+		this.queue.push({ task, request: launchRequest });
+		queueMicrotask(() => this.pump());
+		return task;
+	}
+
+	waitFor(id: string): Promise<TaskRecord> {
+		const current = this.store.get(id);
+		if (!current) return Promise.reject(new Error(`no task ${id}`));
+		if (isFinished(current.status)) return Promise.resolve(current);
+		return new Promise((resolve) => {
+			const list = this.waiters.get(id) ?? [];
+			list.push(resolve);
+			this.waiters.set(id, list);
+		});
+	}
+
+	waitForQuery(id: string): Promise<TaskQuery | undefined> {
+		const current = this.store.get(id);
+		if (!current || isFinished(current.status)) return Promise.resolve(undefined);
+		const first = this.firstQueries.get(id);
+		if (first) return Promise.resolve(first);
+		return new Promise((resolve) => {
+			const list = this.queryWaiters.get(id) ?? [];
+			list.push(resolve);
+			this.queryWaiters.set(id, list);
+		});
+	}
+
+	async reply(id: string, requestId: string, message: string, parentSessionId: string): Promise<boolean> {
+		const task = this.store.get(id);
+		const live = this.live.get(id);
+		if (!task || !live || live.terminal || task.parentSessionId !== parentSessionId || !validChildMessage(message)) return false;
+		const query = live.queries.get(requestId);
+		if (!query || query.replying) return false;
+		query.replying = true;
+		const accepted = await this.sendReply(live, requestId, { id: requestId, kind: "reply", message });
+		if (live.queries.get(requestId) === query) {
+			query.cancel();
+			live.queries.delete(requestId);
+		}
+		return accepted;
+	}
+
+	cancel(id: string): boolean {
+		const queued = this.queue.findIndex((entry) => entry.task.id === id);
+		if (queued >= 0) {
+			this.queue.splice(queued, 1);
+			this.finish(id, TASK_STATUS.CANCELLED, "cancelled before start");
+			return true;
+		}
+		if (!this.live.has(id)) return false;
+		this.requestStop(id, TASK_STATUS.CANCELLED, "cancelled", true);
+		return true;
+	}
+
+	/** Parent-known revocation clears buffered metadata immediately, including
+	 * during an idle provider call. No task/store/status mutation. */
+	discardResponseObservations(id: string): void {
+		const live = this.live.get(id);
+		if (live) { live.observations = undefined; live.observationGuard = undefined; }
+	}
+
+	cancelAll(): number {
+		const ids = [...this.queue.map((entry) => entry.task.id), ...this.live.keys()];
+		return ids.filter((id) => this.cancel(id)).length;
+	}
+
+	steer(id: string, message: string): boolean {
+		if (!this.live.has(id)) return false;
+		void this.send(id, { type: "steer", message });
+		this.store.apply(id, { type: TASK_EVENT.NOTE, text: `steered: ${message}` }, this.deps.now());
+		return true;
+	}
+
+	private pump(): void {
+		while (this.live.size < this.limits.maxConcurrency && this.queue.length > 0) {
+			const entry = this.queue.shift();
+			if (!entry) continue;
+			const { task, request } = entry;
+			this.launch(task.id, request);
+		}
+	}
+
+	// A child that cannot start (missing pi, bad cwd) fails only its task:
+	// spawn exceptions and process errors settle without uncaught host errors.
+	private launch(id: string, request: TaskRequest): void {
+		const detached = this.processControl.platform !== "win32";
+		const hasParentPermissionChannel = request.authorizeParentStandingReviewPermission !== undefined;
+		const env = {
+			...request.env,
+			...(request.extensionPaths ? { [RESEARCH_SELECTION_ENV]: JSON.stringify(request.researchSelection ?? null), [RESEARCH_ARTIFACT_ENV]: JSON.stringify(request.researchArtifact ?? null) } : {}),
+			[CHILD_MARKER]: "1",
+			[IPC_MARKER]: `${this.deps.now()}-${Math.random().toString(36).slice(2)}`,
+			...(hasParentPermissionChannel ? { GENTLE_PI_AGENTS_PARENT_PERMISSION_FD: "3" } : {}),
+		};
+		delete env[REMEDIATION_PLAN_ENV];
+		if (request.sddRemediation) env[REMEDIATION_PLAN_ENV] = JSON.stringify({ plan: request.sddRemediation.plan, scope: request.sddRemediation.scope, selection: request.sddChange });
+		let child: ChildLike;
+		try {
+			child = this.deps.spawn(this.deps.pi.command, [...this.deps.pi.args, ...childArguments(request)], {
+				cwd: request.cwd,
+				env,
+				detached,
+				stdio: hasParentPermissionChannel ? ["pipe", "pipe", "pipe", "pipe", "ipc"] : ["pipe", "pipe", "pipe", "ipc"],
+			});
+		} catch (error) {
+			this.store.update(id, { status: TASK_STATUS.RUNNING, startedAt: this.deps.now(), lastStep: "starting" });
+			this.finish(id, TASK_STATUS.FAILED, `could not start pi: ${error instanceof Error ? error.message : String(error)}`);
+			return;
+		}
+		const processGroup = detached && typeof child.pid === "number" && child.pid > 0 ? child.pid : undefined;
+		const live: LiveTask = { child, mutationStarts: new Map(), pending: new Map(), queries: new Map(), replies: new Map(), cancelStall: () => {}, cancelGrace: () => {}, processGroup, terminal: undefined, childExit: undefined, cleanupDeadlineAt: undefined, quarantined: false, nextId: 0, ipcClosed: false, acknowledgedIpcIds: new Set(), acknowledgedIpcOrder: [] };
+		if (request.prepareResponseObservations) {
+			let ready = false;
+			live.observationPreparation = () => ready;
+			void Promise.resolve().then(() => this.live.get(id) === live && !live.terminal
+				? request.prepareResponseObservations!() : false).then(allowed => { ready = allowed === true; }).catch(() => {});
+		}
+		if (request.collectResponseObservations === true || request.prepareResponseObservations) {
+			live.observationGuard = request.canCollectResponseObservations;
+			live.observations = { agentSettled: false, responses: [], droppedResponses: 0 };
+			if (!request.prepareResponseObservations) this.checkObservationGrant(live);
+		}
+		this.live.set(id, live);
+		const permissionPipe = child.stdio?.[3];
+		if (hasParentPermissionChannel && permissionPipe !== undefined && permissionPipe !== null) {
+			live.permissionBroker = new ParentStandingReviewPermissionBroker(
+				{ readable: permissionPipe, writable: permissionPipe },
+				(repositoryIdentity) => this.live.get(id) === live && !live.terminal && request.authorizeParentStandingReviewPermission?.(repositoryIdentity) === true,
+			);
+		}
+		this.store.update(id, { status: TASK_STATUS.RUNNING, startedAt: this.deps.now(), lastStep: "starting" });
+		child.channel?.unref?.();
+		child.on("error", (error) => this.childError(id, error));
+		child.on("message", (value) => this.receiveChildMessage(id, value));
+		child.on("disconnect", () => this.closeIpc(live));
+		let announced = false;
+		child.on("spawn", () => {
+			if (announced || this.live.get(id) !== live || live.terminal) return;
+			announced = true;
+			try { request.onLaunch?.(); }
+			catch (error) { this.requestStop(id, TASK_STATUS.FAILED, `could not register launched worktree: ${error instanceof Error ? error.message : String(error)}`); }
+		});
+		child.stdin.on("error", () => {});
+		this.armStall(id, live);
+		const lines = new JsonLines((value) => this.receive(id, request, value));
+		child.stdout.setEncoding("utf8");
+		child.stdout.on("data", (chunk: string) => lines.push(chunk));
+		child.stderr?.on("data", () => {});
+		child.on("exit", (code) => this.exited(id, code));
+		if (request.sddRemediation && child.pid === undefined) {
+			this.childError(id, new Error("remediation child has no process ID"));
+			return;
+		}
+		void this.send(id, { type: "get_state" }).then((response) => {
+			const data = response.data as { sessionFile?: unknown; model?: { provider?: unknown; id?: unknown } | null; thinkingLevel?: unknown } | undefined;
+			if (response.success !== true || live.terminal || this.live.get(id) !== live || !data) return;
+			const resolved: Partial<TaskRecord> = {};
+			if (typeof data.sessionFile === "string" && data.sessionFile) resolved.sessionPath = data.sessionFile;
+			if (data.model === null) resolved.model = "default";
+			else if (typeof data.model?.provider === "string" && data.model.provider && typeof data.model.id === "string" && data.model.id) {
+				resolved.model = formatModelRef({ provider: data.model.provider, id: data.model.id });
+			}
+			if (typeof data.thinkingLevel === "string" && ["off", "minimal", "low", "medium", "high", "xhigh", "max"].includes(data.thinkingLevel)) resolved.thinking = data.thinkingLevel;
+			this.store.update(id, resolved);
+		});
+		void this.send(id, { type: "prompt", message: promptText(request) }).then((response) => {
+			if (response.success === false) this.requestStop(id, TASK_STATUS.FAILED, String(response.error ?? "prompt rejected"));
+		});
+	}
+
+	private armStall(id: string, live: LiveTask): void {
+		live.cancelStall();
+		live.cancelStall = this.deps.schedule(() => this.requestStop(id, TASK_STATUS.TIMED_OUT, `stalled for ${Math.round(this.limits.stallTimeoutMs / 60_000)} min`), this.limits.stallTimeoutMs);
+	}
+
+	private send(id: string, command: Record<string, unknown>): Promise<Record<string, unknown>> {
+		const live = this.live.get(id);
+		if (!live) return Promise.resolve({ success: false, error: "task is not running" });
+		live.nextId += 1;
+		const requestId = `r${live.nextId}`;
+		return new Promise((resolve) => {
+			live.pending.set(requestId, { resolve });
+			this.write(live, { id: requestId, ...command });
+		});
+	}
+
+	private receiveChildMessage(id: string, value: unknown): void {
+		const live = this.live.get(id);
+		if (!live || live.ipcClosed) return;
+		const parsed = parseChildFrame(value);
+		if (!parsed.frame) {
+			if (parsed.id && validChildQueryId(parsed.id)) this.sendQueryError(live, parsed.id, parsed.error ?? "invalid child IPC frame");
+			else if (parsed.id) this.acknowledge(live, parsed.id, false, parsed.error ?? "invalid child IPC frame");
+			return;
+		}
+		const task = this.store.get(id);
+		if (!task || live.terminal || isFinished(task.status) || task.parentSessionId === "") {
+			if (parsed.frame.kind === "notification") this.acknowledge(live, parsed.frame.id, false, "task is not a live owned recipient");
+			else this.sendQueryError(live, parsed.frame.id, "task is not a live owned recipient");
+			return;
+		}
+		if (parsed.frame.kind === "notification") {
+			if (live.acknowledgedIpcIds.has(parsed.frame.id)) return;
+			try {
+				if (this.hooks.onNotification?.(task, parsed.frame.message) === false) this.acknowledge(live, parsed.frame.id, false, "task parent is not the active host session");
+				else this.acknowledge(live, parsed.frame.id, true);
+			} catch { this.acknowledge(live, parsed.frame.id, false, "parent rejected notification"); }
+			return;
+		}
+		let query: PendingQuery | undefined;
+		try {
+			if (live.queries.has(parsed.frame.id)) rejectQuery("duplicate query request");
+			if (live.queries.size >= CHILD_QUERY_MAX_INFLIGHT) rejectQuery("too many pending parent queries");
+			query = { replying: false, cancel: this.deps.schedule(() => this.expireQuery(live, parsed.frame!.id), CHILD_QUERY_TIMEOUT_MS) };
+			live.queries.set(parsed.frame.id, query);
+			if (!this.hooks.onQuery) rejectQuery("task parent cannot accept queries");
+			if (this.hooks.onQuery(task, parsed.frame.id, parsed.frame.message) === false) rejectQuery("task parent is not the active host session");
+			if (task.mode === AGENT_MODE.TASK && !this.firstQueries.has(id)) {
+				const first = { taskId: id, requestId: parsed.frame.id };
+				this.firstQueries.set(id, first);
+				for (const resolve of this.queryWaiters.get(id) ?? []) resolve(first);
+				this.queryWaiters.delete(id);
+			}
+		} catch (error) {
+			if (query && live.queries.get(parsed.frame.id) === query) {
+				query.cancel();
+				live.queries.delete(parsed.frame.id);
+			}
+			this.sendQueryError(live, parsed.frame.id, queryRejection(error));
+		}
+	}
+
+	private expireQuery(live: LiveTask, id: string): void {
+		const query = live.queries.get(id);
+		if (!query) return;
+		live.queries.delete(id);
+		if (query.replying) this.settleReply(live, id, false);
+		else this.sendQueryError(live, id, "parent query timed out");
+	}
+
+	private sendQueryError(live: LiveTask, id: string, error: string): void {
+		const safeError = QUERY_REJECTION_ERRORS.has(error) ? error : "parent rejected query";
+		try { live.child.send?.({ id, kind: "reply", error: safeError }, () => {}); }
+		catch { /* Child-owned IPC callback reports transport failure. */ }
+	}
+
+	private acknowledge(live: LiveTask, id: string, accepted: boolean, error?: string): void {
+		if (live.ipcClosed || live.acknowledgedIpcIds.has(id) || !live.child.send) return;
+		live.acknowledgedIpcIds.add(id);
+		live.acknowledgedIpcOrder.push(id);
+		if (live.acknowledgedIpcOrder.length > 64) live.acknowledgedIpcIds.delete(live.acknowledgedIpcOrder.shift()!);
+		try { live.child.send({ id, kind: "ack", accepted, ...(error ? { error } : {}) }, () => {}); }
+		catch { /* Child-owned IPC callback reports transport failure. */ }
+	}
+
+	private sendReply(live: LiveTask, id: string, frame: Record<string, unknown>): Promise<boolean> {
+		return new Promise((resolve) => {
+			live.replies.set(id, { resolve });
+			try {
+				if (!live.child.send) this.settleReply(live, id, false);
+				else live.child.send(frame, (error) => this.settleReply(live, id, !error));
+			} catch { this.settleReply(live, id, false); }
+		});
+	}
+
+	private settleReply(live: LiveTask, id: string, accepted: boolean): void {
+		const pending = live.replies.get(id);
+		if (!pending) return;
+		live.replies.delete(id);
+		pending.resolve(accepted);
+	}
+
+	private closeIpc(live: LiveTask): void {
+		if (live.ipcClosed) return;
+		live.ipcClosed = true;
+		for (const query of live.queries.values()) query.cancel();
+		live.queries.clear();
+		for (const pending of live.replies.values()) pending.resolve(false);
+		live.replies.clear();
+		live.child.channel?.unref?.();
+		try { live.child.disconnect?.(); }
+		catch { /* Channel may already be disconnected. */ }
+	}
+
+	private write(live: LiveTask, payload: Record<string, unknown>): void {
+		try {
+			live.child.stdin.write(`${JSON.stringify(payload)}\n`);
+		} catch {
+			// the child is gone; the exit handler settles the task
+		}
+	}
+
+	private checkObservationGrant(live: LiveTask): void {
+		if (live.observationPreparation) {
+			if (!live.observationPreparation()) live.observations = undefined;
+			live.observationPreparation = undefined; // One chance; late readiness cannot attach.
+		}
+		if (!live.observations || !live.observationGuard) return;
+		try {
+			if (live.observationGuard() === true) return;
+		} catch { /* Policy bookkeeping must not interrupt child execution. */ }
+		live.observations = undefined;
+		live.observationGuard = undefined;
+	}
+
+	private receive(id: string, request: TaskRequest, value: unknown): void {
+		const live = this.live.get(id);
+		if (!live || live.terminal || !value || typeof value !== "object") return;
+		const raw = value as Record<string, unknown>;
+		const remediation = this.store.get(id)?.sddRemediation;
+		if (remediation) observeRemediationTool(remediation, raw);
+		this.armStall(id, live);
+		if (raw.type === "response") {
+			if (!live.observationPreparation) this.checkObservationGrant(live);
+			const pending = typeof raw.id === "string" ? live.pending.get(raw.id) : undefined;
+			if (pending) {
+				live.pending.delete(raw.id as string);
+				pending.resolve(raw);
+			}
+			return;
+		}
+		this.checkObservationGrant(live);
+		for (const event of normalizeRpcEvent(raw, { observeResponses: live.observations !== undefined })) {
+			if (event.type === TASK_EVENT.RESPONSE_OBSERVATION) {
+				const buffer = live.observations;
+				if (buffer) {
+					if (buffer.responses.length < MAX_CHILD_RESPONSE_OBSERVATIONS) buffer.responses.push(event.observation);
+					else buffer.droppedResponses = Math.min(Number.MAX_SAFE_INTEGER, buffer.droppedResponses + 1);
+				}
+				continue; // Separate from store persistence, UI totals and notifications.
+			}
+			this.store.apply(id, event, this.deps.now());
+			if (event.type === TASK_EVENT.TOOL_START && event.callId) {
+				live.mutationStarts.delete(event.callId);
+				if ((event.name === "write" || event.name === "edit") && typeof event.args.path === "string" && event.args.path.trim()) {
+					live.mutationStarts.set(event.callId, { toolName: event.name, toolCallId: event.callId, path: event.args.path });
+				}
+			}
+			if (event.type === TASK_EVENT.TOOL_END) {
+				const mutation = live.mutationStarts.get(event.callId);
+				live.mutationStarts.delete(event.callId);
+				const task = this.store.get(id);
+				if (mutation && task && raw.isError === false && !event.isError) {
+					try { void Promise.resolve(this.hooks.onSuccessfulMutation?.(task, mutation)).catch(() => {}); }
+					catch { /* Bookkeeping failure must not rewrite a successful tool or stop the child. */ }
+				}
+			}
+			if (event.type === TASK_EVENT.ASK) void this.answer(id, request, live, event.request, raw);
+			if (event.type === TASK_EVENT.AGENT_SETTLED) {
+				if (live.observations) live.observations.agentSettled = true;
+				const terminal = this.store.get(id);
+				if (terminal?.error) this.requestStop(id, TASK_STATUS.FAILED, terminal.error);
+				else if (terminal?.result) this.requestStop(id, TASK_STATUS.COMPLETED, null);
+				else this.requestStop(id, TASK_STATUS.FAILED, "assistant settled without a final report");
+			}
+		}
+	}
+
+	// Task-mode subagents may ask the human through the host; background ones
+	// get their dialog cancelled so they never block on nobody.
+	private async answer(id: string, request: TaskRequest, live: LiveTask, ask: AskRequest, raw: Record<string, unknown>): Promise<void> {
+		let answer: AskAnswer = { cancelled: true };
+		if (request.mode === "task") {
+			try {
+				answer = await this.hooks.askUser(id, ask, raw);
+			} catch {
+				answer = { cancelled: true };
+			}
+		}
+		if (this.live.get(id) !== live || live.terminal) return;
+		this.write(live, { type: "extension_ui_response", id: ask.id, ...answer });
+		const current = this.store.get(id);
+		if (current?.status === TASK_STATUS.WAITING) this.store.update(id, { status: TASK_STATUS.RUNNING, lastStep: answer.cancelled ? "question dismissed" : "answered" });
+	}
+
+	// POSIX children start detached, so their PID is the owned process-group ID.
+	// Windows uses ChildProcess.kill only: Node has no equivalent tree guarantee.
+	private signal(live: LiveTask, signal: NodeJS.Signals): void {
+		if (live.processGroup !== undefined) {
+			try {
+				this.processControl.kill(-live.processGroup, signal);
+				return;
+			} catch {
+				// The owned group is already gone; the child handle may still observe exit.
+			}
+		}
+		try {
+			live.child.kill(signal);
+		} catch {
+			// already gone
+		}
+	}
+
+	private requestStop(id: string, status: TaskRecord["status"], error: string | null, abort = false): void {
+		const live = this.live.get(id);
+		if (!live || live.terminal) return;
+		live.terminal = { status, error };
+		live.mutationStarts.clear();
+		live.cleanupDeadlineAt = this.deps.now() + GROUP_CONFIRM_DEADLINE_MS;
+		live.permissionBroker?.close();
+		this.closeIpc(live);
+		live.cancelStall();
+		if (abort) void this.send(id, { type: "abort" });
+		this.signal(live, "SIGTERM");
+		live.cancelGrace = this.deps.schedule(() => {
+			if (this.live.get(id) !== live) return;
+			this.signal(live, "SIGKILL");
+			this.confirmGroupExit(id, live);
+		}, TERMINATION_GRACE_MS);
+	}
+
+	// A false result is ambiguous, so the probe reports which one it is: an ESRCH
+	// result proves the group is gone, while an absent process group means the
+	// question cannot be asked at all. Only the first justifies treating the exit as
+	// complete without an observed exit event.
+	private probeGroup(live: LiveTask): "present" | "gone" | "unavailable" {
+		if (live.processGroup === undefined) return "unavailable";
+		try {
+			this.processControl.kill(-live.processGroup, 0);
+			return "present";
+		} catch (error) {
+			return (error as NodeJS.ErrnoException).code === "ESRCH" ? "gone" : "present";
+		}
+	}
+
+	private groupExists(live: LiveTask): boolean {
+		return this.probeGroup(live) === "present";
+	}
+
+	private confirmGroupExit(id: string, live: LiveTask): void {
+		if (this.live.get(id) !== live) return;
+		const group = this.probeGroup(live);
+		if (group === "present") {
+			if (this.deps.now() >= (live.cleanupDeadlineAt ?? 0)) {
+				live.cancelGrace();
+				live.quarantined = true;
+				this.finish(id, TASK_STATUS.FAILED, `process cleanup unconfirmed after ${GROUP_CONFIRM_DEADLINE_MS}ms; capacity quarantined`, live);
+				return;
+			}
+			live.cancelGrace = this.deps.schedule(() => this.confirmGroupExit(id, live), GROUP_CONFIRM_MS);
+			return;
+		}
+		if (group === "gone") {
+			// No process remains in the group, so the exit is complete whether or not
+			// the child's own exit event was ever observed. Completing here also frees
+			// the concurrency slot; finishing without it would leave the task recorded
+			// while its slot stayed occupied and queued work never pumped.
+			this.completeExit(id, live);
+			return;
+		}
+		if (live.childExit !== undefined) {
+			this.completeExit(id, live);
+			return;
+		}
+		// With no process group to probe, an observed exit is the only confirmation
+		// available. Wait for it within the deadline, then quarantine instead of
+		// completing on an assumption, and never return without either.
+		if (this.deps.now() >= (live.cleanupDeadlineAt ?? 0)) {
+			live.cancelGrace();
+			live.quarantined = true;
+			this.finish(id, TASK_STATUS.FAILED, `child exit unconfirmed after ${GROUP_CONFIRM_DEADLINE_MS}ms; capacity quarantined`, live);
+			return;
+		}
+		live.cancelGrace = this.deps.schedule(() => this.confirmGroupExit(id, live), GROUP_CONFIRM_MS);
+	}
+
+	private childError(id: string, error: Error): void {
+		const live = this.live.get(id);
+		if (!live) return;
+		// Node leaves pid undefined when spawn failed; a live PID must still exit
+		// before its slot is released, even if its handle later emits an error.
+		if (live.child.pid !== undefined) {
+			this.requestStop(id, TASK_STATUS.FAILED, `pi process error: ${error.message}`);
+			return;
+		}
+		live.permissionBroker?.close();
+		this.closeIpc(live);
+		live.cancelStall();
+		live.cancelGrace();
+		this.live.delete(id);
+		this.finish(id, TASK_STATUS.FAILED, `could not start pi: ${error.message}`, live);
+	}
+
+	private exited(id: string, code: number | null): void {
+		const live = this.live.get(id);
+		if (!live) return;
+		live.childExit = code;
+		if (this.groupExists(live)) {
+			if (!live.terminal) this.requestStop(id, TASK_STATUS.FAILED, `pi exited with code ${code ?? "unknown"} before agent_settled`);
+			return;
+		}
+		this.completeExit(id, live);
+	}
+
+	private completeExit(id: string, live: LiveTask): void {
+		live.permissionBroker?.close();
+		this.closeIpc(live);
+		live.cancelStall();
+		live.cancelGrace();
+		this.live.delete(id);
+		// Quarantine already notified completion, but its retained slot is now free.
+		if (live.quarantined) {
+			queueMicrotask(() => this.pump());
+			return;
+		}
+		const terminal = live.terminal;
+		this.finish(id, terminal ? terminal.status : TASK_STATUS.FAILED, terminal ? terminal.error : `pi exited with code ${live.childExit ?? "unknown"} before agent_settled`, live);
+	}
+
+	private finish(id: string, status: TaskRecord["status"], error: string | null, live?: LiveTask): void {
+		const current = this.store.get(id);
+		if (!current || isFinished(current.status) || this.finalizingRemediation.has(id)) return;
+		const finalize = this.remediationFinalizers.get(id);
+		if (finalize) {
+			this.finalizingRemediation.add(id);
+			const terminal = { ...current, status, error };
+			void finalize(terminal, { spawned: typeof live?.child.pid === "number", exited: live?.childExit !== undefined, cleanupConfirmed: !live || !live.quarantined && live.childExit !== undefined }).then(() => {
+				status = terminal.status;
+				error = terminal.error;
+			}).catch(() => {
+				status = TASK_STATUS.FAILED;
+				error = "Native remediation settlement could not be durably finalized; retain task history and reconcile before further execution";
+			}).finally(() => {
+				this.remediationFinalizers.delete(id);
+				this.finalizingRemediation.delete(id);
+				this.finish(id, status, error, live);
+			});
+			return;
+		}
+		const finished = this.store.update(id, { status, endedAt: this.deps.now(), error, lastStep: error ?? "done" });
+		if (finished) {
+			if (live) this.checkObservationGrant(live);
+			const buffer = live?.observations;
+			const snapshot: ChildObservationSnapshot | undefined = buffer ? Object.freeze({
+				coverage: "final_assistant_messages_only", agentSettled: buffer.agentSettled,
+				responses: Object.freeze(buffer.responses.slice()), droppedResponses: buffer.droppedResponses,
+			}) : undefined;
+			if (live) {
+				live.observations = undefined; // Also release quarantined buffers.
+				live.observationGuard = undefined;
+			}
+			this.hooks.onFinish?.(finished, snapshot);
+			for (const resolve of this.waiters.get(id) ?? []) resolve(finished);
+			this.waiters.delete(id);
+			for (const resolve of this.queryWaiters.get(id) ?? []) resolve(undefined);
+			this.queryWaiters.delete(id);
+			this.firstQueries.delete(id);
+		}
+		queueMicrotask(() => this.pump());
+	}
+}
+
+// Human-readable suffix for an abort signal's reason, so a cancelled tool call is
+// distinguishable in the record and the notification rather than reported only as
+// "aborted". Returns an empty string when there is no usable reason.
+export function abortReasonText(reason: unknown): string {
+	if (reason === undefined) return "";
+	const message =
+		reason instanceof Error && reason.message.length > 0
+			? reason.message
+			: typeof reason === "string" && reason.length > 0
+				? reason
+				: "";
+	return message.length > 0 ? ` (${message})` : "";
+}