gentle-pi 2.5.0 → 2.6.0

package/lib/agents-runner.ts

@@ -1,7 +1,10 @@
+import { createHash } from "node:crypto";
 import type { Duplex, Readable, Writable } from "node:stream";
-import { formatModelRef, type AgentDefinition, type AgentMode, type ModelRef } from "./agents-config.ts";
+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 TaskRecord, type TaskStore } from "./agents-protocol.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
@@ -15,15 +18,19 @@ export interface ChildLike {
 	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">;
+	stdio?: Array<"pipe" | "ignore" | "inherit" | "ipc">;
 }
 
 export type Spawn = (command: string, args: string[], options: SpawnOptions) => ChildLike;
@@ -57,12 +64,137 @@ export interface AskAnswer {
 	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>;
-	onFinish?(task: TaskRecord): void;
+	/** 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;
@@ -75,6 +207,29 @@ export interface TaskRequest {
 	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;
@@ -90,9 +245,23 @@ 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;
@@ -102,21 +271,56 @@ interface LiveTask {
 	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 ? request.agent.tools : DEFAULT_TOOLS;
+	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;
@@ -162,7 +366,8 @@ export class JsonLines {
 }
 
 export function promptText(request: TaskRequest): string {
-	return request.context ? `${request.prompt}\n\n## Context\n${request.context}` : request.prompt;
+	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 {
@@ -173,7 +378,11 @@ export class AgentRunner {
 	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) {
@@ -184,14 +393,22 @@ export class AgentRunner {
 		this.processControl = deps.process ?? hostProcess;
 	}
 
-	run(request: TaskRequest): TaskRecord {
+	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,
@@ -212,7 +429,22 @@ export class AgentRunner {
 			cost: 0,
 		};
 		this.store.add(task);
-		this.queue.push({ task, request });
+		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;
 	}
@@ -228,6 +460,33 @@ export class AgentRunner {
 		});
 	}
 
+	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) {
@@ -240,6 +499,13 @@ export class AgentRunner {
 		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;
@@ -255,7 +521,9 @@ export class AgentRunner {
 	private pump(): void {
 		while (this.live.size < this.limits.maxConcurrency && this.queue.length > 0) {
 			const entry = this.queue.shift();
-			if (entry) this.launch(entry.task.id, entry.request);
+			if (!entry) continue;
+			const { task, request } = entry;
+			this.launch(task.id, request);
 		}
 	}
 
@@ -266,16 +534,20 @@ export class AgentRunner {
 		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,
-				...(hasParentPermissionChannel ? { stdio: ["pipe", "pipe", "pipe", "pipe"] } : {}),
+				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" });
@@ -283,7 +555,18 @@ export class AgentRunner {
 			return;
 		}
 		const processGroup = detached && typeof child.pid === "number" && child.pid > 0 ? child.pid : undefined;
-		const live: LiveTask = { child, pending: new Map(), cancelStall: () => {}, cancelGrace: () => {}, processGroup, terminal: undefined, childExit: undefined, cleanupDeadlineAt: undefined, quarantined: false, nextId: 0 };
+		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) {
@@ -293,7 +576,17 @@ export class AgentRunner {
 			);
 		}
 		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));
@@ -301,9 +594,21 @@ export class AgentRunner {
 		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?: string } | undefined;
-			if (!live.terminal && this.live.get(id) === live && data?.sessionFile) this.store.update(id, { sessionPath: data.sessionFile });
+			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"));
@@ -326,6 +631,104 @@ export class AgentRunner {
 		});
 	}
 
+	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`);
@@ -334,12 +737,28 @@ export class AgentRunner {
 		}
 	}
 
+	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);
@@ -347,10 +766,35 @@ export class AgentRunner {
 			}
 			return;
 		}
-		for (const event of normalizeRpcEvent(raw)) {
+		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);
@@ -398,8 +842,10 @@ export class AgentRunner {
 		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");
@@ -410,29 +856,59 @@ export class AgentRunner {
 		}, TERMINATION_GRACE_MS);
 	}
 
-	private groupExists(live: LiveTask): boolean {
-		if (live.processGroup === undefined) return false;
+	// 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 true;
+			return "present";
 		} catch (error) {
-			return (error as NodeJS.ErrnoException).code !== "ESRCH";
+			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;
-		if (this.groupExists(live)) {
+		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`);
+				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 (live.childExit !== undefined) this.completeExit(id, live);
+		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 {
@@ -445,10 +921,11 @@ export class AgentRunner {
 			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}`);
+		this.finish(id, TASK_STATUS.FAILED, `could not start pi: ${error.message}`, live);
 	}
 
 	private exited(id: string, code: number | null): void {
@@ -464,6 +941,7 @@ export class AgentRunner {
 
 	private completeExit(id: string, live: LiveTask): void {
 		live.permissionBroker?.close();
+		this.closeIpc(live);
 		live.cancelStall();
 		live.cancelGrace();
 		this.live.delete(id);
@@ -473,18 +951,62 @@ export class AgentRunner {
 			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`);
+		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): void {
+	private finish(id: string, status: TaskRecord["status"], error: string | null, live?: LiveTask): void {
 		const current = this.store.get(id);
-		if (!current || isFinished(current.status)) return;
+		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) {
-			this.hooks.onFinish?.(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})` : "";
+}