@gajae-code/coding-agent 0.11.7 → 0.11.8

package/src/sdk/bus/index.ts

@@ -31,6 +31,7 @@ import { ThinkingLevel } from "@gajae-code/agent-core";
 import type { ImageContent, TextContent, Tool } from "@gajae-code/ai";
 import { NotificationServer, nativeBuildInfo } from "@gajae-code/natives";
 import { logger, postmortem, VERSION } from "@gajae-code/utils";
+import { projectModelProfileCatalog } from "../../config/model-profile-contract";
 import { Settings } from "../../config/settings";
 import type { ExtensionAPI, ExtensionCommandContext, ExtensionContext } from "../../extensibility/extensions";
 import { toAgentWireEventPayload } from "../../modes/shared/agent-wire/event-envelope";
@@ -59,13 +60,13 @@ import { SessionSdkHost, shouldHostSdk } from "../host";
 import { type ControlSurface, dispatchControl } from "../host/control";
 import { CursorRegistry, QueryHandlers, RevisionStore, type SessionSurface } from "../host/query";
 import { projectQ10Models } from "../models.js";
+import { PROMPT_CLIENT_REF_MAX_LENGTH } from "../prompt-status";
 import { OPERATIONS } from "../protocol/operation-registry";
 import {
 	lifecycleStartupCapabilityForApi,
 	normalizeSdkStartupFailure,
 	type SdkStartupFailure,
 } from "../startup-capability";
-
 import { registerTelegramFileSink } from "./attachment-registry";
 import { ensureDiscordDaemon, ensureSlackDaemon } from "./chat-daemon-control";
 import {
@@ -81,6 +82,7 @@ import {
 import { telegramControlCommandUsage } from "./config-commands";
 import { imageAttachmentsFromMessage, notificationActionPayload, summaryFromMessage, truncate } from "./helpers";
 import { assertNativeRuntimeCompatibility } from "./native-runtime-compatibility";
+import { createPromptReconciliation, sanitizePromptFailure } from "./prompt-reconciliation";
 import { NotificationSessionController, type NotificationSessionRuntime } from "./session-control";
 import {
 	ASK_SELECTED_ACK_CAPABILITY,
@@ -401,6 +403,7 @@ interface UnattendedGatePresentation {
 	question: string;
 	options: string[];
 	controls: readonly AskRemoteControl[];
+	recommendedIndex?: number;
 	multi: boolean;
 	allowEmpty: boolean;
 	navigationLabel?: "Next" | "Done";
@@ -409,6 +412,14 @@ interface UnattendedGatePresentation {
 	onActivated?: (actionId: string, lease: { actionId: string; registrationEpoch: number }) => void;
 	onClosed?: () => void;
 }
+function recommendedIndexFromGateOptions(options: readonly unknown[]): number | undefined {
+	const descriptions = options.map(option => (option as { description?: unknown }).description);
+	const recommended = descriptions.filter(description => description === "recommended");
+	return recommended.length === 1 &&
+		descriptions.every(description => description === undefined || description === "recommended")
+		? descriptions.indexOf("recommended")
+		: undefined;
+}
 
 type RetireStatus = "retired" | "already_terminal" | "claimed" | "stale";
 type DirectControlOutcome = "accepted" | "rejected" | "unknown";
@@ -739,6 +750,9 @@ export class PresentationArbiter {
 									? `(${presentation.selectedOptions.length} selected) ${presentation.question}`
 									: presentation.question,
 							options: presentation.options,
+							...(presentation.recommendedIndex === undefined
+								? {}
+								: { recommendedIndex: presentation.recommendedIndex }),
 							controls: presentation.multi
 								? [
 										{
@@ -906,6 +920,13 @@ interface SessionRuntime {
 	/** Records a correlated prompt terminal boundary after agent unwind. */
 	/** Atomically claims a correlated prompt terminal boundary after agent unwind. */
 	recordPromptTerminal: (correlation: { commandId: string; turnId: string } | undefined) => boolean;
+	/** Transitions the authoritative reconciliation record at lifecycle ingress; terminal outcomes settle once. */
+	notePromptReconciliation: (
+		correlation: { commandId: string; turnId: string } | undefined,
+		frame: { type: "agent_start" | "agent_end" } | { type: "agent_failed"; error: unknown },
+	) => void;
+	/** Settles and emits one sanitized correlated prompt failure. */
+	emitPromptFailure: (correlation: { commandId: string; turnId: string }, error: unknown) => void;
 	/** Records correlated lifecycle frames for replay and delivers them only to the accepted requester after acknowledgement. */
 	emitPromptLifecycle: (
 		correlation: { commandId: string; turnId: string } | undefined,
@@ -939,6 +960,12 @@ interface SessionRuntime {
 	turnClosed?: boolean;
 	/** Finalized while provisional policy was held; flush exactly once on stable activation. */
 	pendingFinal?: { text?: string; messageRef?: string };
+	/**
+	 * Lean-mode deferred final answer: latest assistant text observed at `turn_end`,
+	 * emitted once at `agent_end` so intermediate tool-turn narration does not flood
+	 * remote clients. Cleared after flush or when replaced by a newer turn.
+	 */
+	pendingSettled?: { text: string; messageRef?: string };
 	/** Durable gates emitted while ownership is provisional; presented only after stable activation. */
 	deferredGatePresentations: Array<() => void>;
 	/** SDK control frames received during provisional ownership; replayed only after stable activation. */
@@ -954,7 +981,6 @@ interface SessionRuntime {
 const SENSITIVE_MODEL_LABEL =
 	/(?:\b(?:https?|wss?):\/\/|\b[a-z0-9._%+-]+@[a-z0-9.-]+\.[a-z]{2,}\b|\b(?:api[-_ ]?key|access[-_ ]?token|bearer|secret|password|account(?:\s*id)?|email|exception|stack trace)\b|\b(?:sk|pk|rk)-[A-Za-z0-9_-]{12,}\b)/i;
 const TOOL_SUMMARY_MAX = 280;
-const EMPTY_CAPABILITIES: ReadonlySet<string> = new Set();
 
 /** Stable projection of the tool-owned safe-display seam (never the full Tool surface). */
 type SafeSummaryTool = Pick<Tool, "safeSummary" | "safeSummaryFields">;
@@ -1019,6 +1045,14 @@ function pushSessionFrame(
 	runtime.server.pushFrame(JSON.stringify(frame));
 }
 
+async function pushTerminalSessionFrame(
+	runtime: Pick<SessionRuntime, "server" | "host">,
+	frame: { type: "session_closed"; sessionId: string },
+): Promise<boolean> {
+	runtime.host.emitEvent({ kind: frame.type, payload: frame });
+	return await runtime.server.pushFrameAndWait(JSON.stringify(frame), 1_000);
+}
+
 function pushFileAttachment(
 	runtime: Pick<SessionRuntime, "server" | "host">,
 	frame: { type: "file_attachment"; sessionId: string; name: string; mime?: string; caption?: string },
@@ -1593,6 +1627,7 @@ function registerInteractiveAnswerSource(
 					question: request.question,
 					options: request.options,
 					controls: request.controls,
+					recommendedIndex: request.recommendedIndex,
 					multi: false,
 					allowEmpty: false,
 					selectedOptions: [],
@@ -1755,6 +1790,7 @@ function sdkQuerySurface(
 		followupQueueDepth: 0,
 	}),
 	configOverrides: ReadonlyMap<string, unknown> = new Map(),
+	promptStatusLookup: (selector: { commandId?: string; turnId?: string; clientRef?: string }) => unknown,
 ): SessionSurface {
 	const metadata = () => ({
 		sessionId: id,
@@ -1822,6 +1858,8 @@ function sdkQuerySurface(
 			const currentThinkingLevel = api.getThinkingLevel();
 			return projectQ10Models({ models, currentModel, currentThinkingLevel });
 		},
+		getModelProfiles: () =>
+			projectModelProfileCatalog(ctx.modelRegistry.getModelProfiles(), ctx.modelRegistry.getError()),
 		getSkillState: () => ctx.getSkillState(),
 		getGates: () => {
 			const workflowGate = ctx.workflowGate;
@@ -1861,6 +1899,8 @@ function sdkQuerySurface(
 		getExtensions: () => ctx.getExtensions(),
 		getArtifactRange: (id, offset, length) => ctx.getArtifactRange?.(id, offset, length),
 		getJobs: () => ctx.getJobs(),
+		getPromptStatus: (selector: { commandId?: string; turnId?: string; clientRef?: string }) =>
+			promptStatusLookup(selector),
 		installedQueries: installedOperations(ctx, "query"),
 	};
 }
@@ -1886,10 +1926,14 @@ function sdkControlSurface(
 	onPromptAccepted: (
 		correlation: { commandId: string; turnId: string },
 		requesterConnectionId?: string,
+		clientRef?: string,
+		trackReconciliation?: boolean,
 	) => void = () => {},
 	onPromptFailed: (correlation: { commandId: string; turnId: string }, error: unknown) => void = () => {},
 	acceptGateResolution: () => boolean,
 	trackGateResolution: <T>(resolution: Promise<T>) => Promise<T>,
+	admitPrompt: (clientRef?: string) => void,
+	releasePromptAdmission: (clientRef?: string) => void,
 	settings?: Settings,
 	configOverrides: Map<string, unknown> = new Map(),
 	configRevision: { current: number } = { current: 0 },
@@ -1966,19 +2010,35 @@ function sdkControlSurface(
 		deliverAs?: "steer" | "followUp",
 		rejectWhenBusy = false,
 		requesterConnectionId?: string,
+		clientRef?: string,
+		trackReconciliation = false,
 	) => {
-		if (forceFresh && isSessionBusy()) {
-			throw Object.assign(new Error("Previous turn did not finish aborting before replacement prompt submission."), {
-				code: "busy",
+		const trimmedClientRef = typeof clientRef === "string" ? clientRef.trim() : undefined;
+		if (clientRef !== undefined && (!trimmedClientRef || trimmedClientRef.length > PROMPT_CLIENT_REF_MAX_LENGTH))
+			throw Object.assign(new Error("clientRef must be a non-empty string of at most 128 characters."), {
+				code: "invalid_input",
 			});
+		if (trackReconciliation) admitPrompt(trimmedClientRef);
+		try {
+			if (forceFresh && isSessionBusy()) {
+				throw Object.assign(
+					new Error("Previous turn did not finish aborting before replacement prompt submission."),
+					{
+						code: "busy",
+					},
+				);
+			}
+			if (rejectWhenBusy && isSessionBusy())
+				throw Object.assign(
+					new Error("turn.prompt is unavailable while the agent is busy; use turn.steer explicitly."),
+					{
+						code: "busy",
+					},
+				);
+		} catch (error) {
+			if (trackReconciliation) releasePromptAdmission(trimmedClientRef);
+			throw error;
 		}
-		if (rejectWhenBusy && isSessionBusy())
-			throw Object.assign(
-				new Error("turn.prompt is unavailable while the agent is busy; use turn.steer explicitly."),
-				{
-					code: "busy",
-				},
-			);
 		const promptImages = Array.isArray(images) ? (images as { data: string; mimeType?: string }[]) : [];
 		const content: string | (TextContent | ImageContent)[] =
 			promptImages.length > 0
@@ -2010,7 +2070,7 @@ function sdkControlSurface(
 		const onPreflightAccepted = () => {
 			if (preflightSettled) return;
 			accepted = true;
-			onPromptAccepted(correlation, requesterConnectionId);
+			onPromptAccepted(correlation, requesterConnectionId, trimmedClientRef, trackReconciliation);
 			settlePreflight({ status: "accepted" });
 		};
 		// Do not acknowledge the prompt until AgentSession's async preflight
@@ -2047,13 +2107,17 @@ function sdkControlSurface(
 		try {
 			const result = await preflight.promise;
 			if (result.status === "rejected") throw result.error;
-			return { commandId, turnId, accepted: true };
+			return { commandId, turnId, accepted: true, ...(trimmedClientRef ? { clientRef: trimmedClientRef } : {}) };
+		} catch (error) {
+			if (trackReconciliation) releasePromptAdmission(trimmedClientRef);
+			throw error;
 		} finally {
 			pendingPreflightCancellations.delete(cancelPreflight);
 		}
 	};
 	const surface: ControlSurface & { cancelPendingPreflights(): void } = {
-		prompt: (text, images) => submitPrompt(text, images, false, undefined, true, controlRequesterContext.getStore()),
+		prompt: (text, images, clientRef) =>
+			submitPrompt(text, images, false, undefined, true, controlRequesterContext.getStore(), clientRef, true),
 		steer: text => sendSteer(text),
 		followUp: text => submitPrompt(text, undefined, false, "followUp", false, controlRequesterContext.getStore()),
 		abort: () => {
@@ -2839,7 +2903,6 @@ export function createNotificationsExtension(
 		"session.branch",
 	]);
 	const sessionId = (ctx: ExtensionContext): string => ctx.sessionManager.getSessionId();
-	const sleep = (ms: number): Promise<void> => new Promise(resolve => setTimeout(resolve, ms));
 
 	async function stopSession(
 		id: string,
@@ -2914,6 +2977,12 @@ export function createNotificationsExtension(
 		try {
 			rt.workflowGate?.setRuntimeTurnProvider?.(null);
 		} catch {}
+		try {
+			const delivered = await pushTerminalSessionFrame(rt, { type: "session_closed", sessionId: id });
+			if (!delivered) logger.warn("notifications: session_closed socket delivery was not acknowledged");
+		} catch (e) {
+			logger.warn(`notifications: session_closed failed: ${String(e)}`);
+		}
 		await rt.waitForGateResolutionQuiescence();
 		try {
 			rt.disposeAckRecoveryParticipant();
@@ -2955,14 +3024,6 @@ export function createNotificationsExtension(
 			ownerReleaseFailures.push(e);
 			logger.warn(`sdk query snapshots: close failed: ${String(e)}`);
 		}
-		let closeFrameSent = false;
-		try {
-			pushSessionFrame(rt, { type: "session_closed", sessionId: id });
-			closeFrameSent = true;
-		} catch (e) {
-			logger.warn(`notifications: session_closed failed: ${String(e)}`);
-		}
-		if (closeFrameSent) await sleep(100);
 		let serverStopped = rt.serverStopped;
 		if (!serverStopped) {
 			try {
@@ -3142,11 +3203,20 @@ export function createNotificationsExtension(
 			failed: boolean;
 			error: unknown;
 			terminal: boolean;
+			retainCorrelation: boolean;
 			createdAt: number;
 			bufferedFrames: Array<PromptLifecycleFrame | Record<string, unknown>>;
 		};
 		const promptSubmissions = new Map<string, PromptSubmission>();
 		const promptTerminalTombstones = new Map<string, number>();
+		// Authoritative bounded reconciliation state for Q26 turn.prompt_status
+		// (contract documented in ./prompt-reconciliation and ../prompt-status).
+		// Active records never age into terminal; documented TTL/capacity
+		// eviction is the only removal, after which lookups report `unknown`.
+		const reconciliation = createPromptReconciliation();
+		const admitPromptSubmission = reconciliation.admit;
+		const notePromptReconciliationAccepted = reconciliation.noteAccepted;
+		const lookupPromptStatus = reconciliation.lookup;
 		const removePendingPromptCorrelation = (correlation: { commandId: string; turnId: string }) => {
 			const pendingIndex = pendingPromptCorrelations.findIndex(
 				candidate => candidate.commandId === correlation.commandId && candidate.turnId === correlation.turnId,
@@ -3164,14 +3234,20 @@ export function createNotificationsExtension(
 			removePendingPromptCorrelation(correlation);
 			addTerminalTombstone(key);
 		};
+		const expirePromptDelivery = (key: string, submission: PromptSubmission) => {
+			promptSubmissions.delete(key);
+			if (!submission.terminal && submission.retainCorrelation) return;
+			const [commandId, turnId] = key.split(":", 2);
+			if (!commandId || !turnId) return;
+			removePendingPromptCorrelation({ commandId, turnId });
+			addTerminalTombstone(key);
+		};
 		const cleanupPromptRecords = (now = Date.now()) => {
+			reconciliation.cleanup();
 			for (const [key, expiresAt] of promptTerminalTombstones)
 				if (expiresAt <= now) promptTerminalTombstones.delete(key);
 			for (const [key, submission] of promptSubmissions)
-				if (submission.createdAt + PROMPT_SUBMISSION_TTL_MS <= now) {
-					const [commandId, turnId] = key.split(":", 2);
-					if (commandId && turnId) finalizePrompt(key, { commandId, turnId });
-				}
+				if (submission.createdAt + PROMPT_SUBMISSION_TTL_MS <= now) expirePromptDelivery(key, submission);
 		};
 		const abandonPrompt = (submission: PromptSubmission) => {
 			submission.abandoned = true;
@@ -3182,6 +3258,7 @@ export function createNotificationsExtension(
 			frame: PromptLifecycleFrame,
 		) => {
 			cleanupPromptRecords();
+
 			if (!correlation || !runtime) {
 				emitAgentLifecycle(runtime!, frame as Extract<PromptLifecycleFrame, { type: "agent_start" | "agent_end" }>);
 				return;
@@ -3247,15 +3324,21 @@ export function createNotificationsExtension(
 		const recordPromptAccepted = (
 			correlation: { commandId: string; turnId: string },
 			requesterConnectionId?: string,
+			clientRef?: string,
+			trackReconciliation = false,
 		) => {
-			if (!requesterConnectionId) return;
+			if (!requesterConnectionId) {
+				// No delivery owner: tracked prompts cannot be reconciled. Release
+				// their admission reservation instead of leaking the active slot.
+				if (trackReconciliation) reconciliation.releaseAdmission(clientRef);
+				return;
+			}
+			if (trackReconciliation) notePromptReconciliationAccepted(correlation, clientRef);
 			cleanupPromptRecords();
 			while (promptSubmissions.size >= PROMPT_SUBMISSION_CAPACITY) {
 				const oldest = promptSubmissions.entries().next().value as [string, PromptSubmission] | undefined;
 				if (!oldest) break;
-				const [key] = oldest;
-				const [commandId, turnId] = key.split(":", 2);
-				if (commandId && turnId) finalizePrompt(key, { commandId, turnId });
+				expirePromptDelivery(oldest[0], oldest[1]);
 			}
 			pendingPromptCorrelations.push(correlation);
 			promptSubmissions.set(promptSubmissionKey(correlation), {
@@ -3265,6 +3348,7 @@ export function createNotificationsExtension(
 				failed: false,
 				error: undefined,
 				terminal: false,
+				retainCorrelation: trackReconciliation,
 				createdAt: Date.now(),
 				bufferedFrames: [],
 			});
@@ -3280,17 +3364,15 @@ export function createNotificationsExtension(
 			return true;
 		};
 		const emitPromptFailure = (correlation: { commandId: string; turnId: string }, error: unknown) => {
+			const sanitized = sanitizePromptFailure(error);
+			reconciliation.noteTransition(correlation, { type: "agent_failed", error: sanitized });
 			const submission = promptSubmissions.get(promptSubmissionKey(correlation));
 			if (!submission || !runtime || !recordPromptTerminal(correlation)) return;
-			const candidate = error as { code?: unknown; message?: unknown };
 			emitPromptLifecycle(correlation, {
 				type: "agent_failed",
 				sessionId: runtime.id,
 				...correlation,
-				error: {
-					code: typeof candidate.code === "string" ? candidate.code : "internal",
-					message: typeof candidate.message === "string" ? candidate.message : "Prompt submission failed.",
-				},
+				error: sanitized,
 			});
 		};
 		const recordPromptFailure = (correlation: { commandId: string; turnId: string }, error: unknown) => {
@@ -3333,6 +3415,7 @@ export function createNotificationsExtension(
 					};
 				},
 				configOverrides,
+				lookupPromptStatus,
 			),
 			id,
 			revisions,
@@ -3348,6 +3431,8 @@ export function createNotificationsExtension(
 			recordPromptFailure,
 			() => runtime?.stopping !== true,
 			trackGateResolution,
+			admitPromptSubmission,
+			reconciliation.releaseAdmission,
 			settings,
 			configOverrides,
 			configRevision,
@@ -3406,7 +3491,7 @@ export function createNotificationsExtension(
 			stateRoot,
 			token,
 			sendFrame: (connectionId, frame) => sendSdkFrame(connectionId, frame),
-			connectionCapabilities: connectionId => hostCapCache.get(connectionId) ?? EMPTY_CAPABILITIES,
+			connectionCapabilities: connectionId => hostCapCache.get(connectionId),
 			installProviderDefinitions,
 			onProviderDefinitionsRemoved: removeProviderDefinitions,
 			onFrame: handler => {
@@ -3478,6 +3563,7 @@ export function createNotificationsExtension(
 						},
 					),
 				);
+
 				if (rotatesIdentity && response.ok !== true) {
 					identityControlInFlight = false;
 					deferredIdentityRotation = undefined;
@@ -3547,6 +3633,8 @@ export function createNotificationsExtension(
 			pendingPromptCorrelations,
 			activePromptCorrelation: undefined,
 			recordPromptTerminal,
+			notePromptReconciliation: reconciliation.noteTransition,
+			emitPromptFailure,
 			emitPromptLifecycle,
 			emitPromptEvent,
 			pendingInbound: new Set<number>(),
@@ -3608,6 +3696,13 @@ export function createNotificationsExtension(
 					if (!frame || typeof frame !== "object") return;
 					const typedFrame = frame as Record<string, unknown>;
 					if (typedFrame.type === "ephemeral_turn" || typedFrame.type === "ephemeral_turn_cancel") return;
+					if (typedFrame.type === "event_replay") {
+						const capabilities = Array.isArray(typedFrame.capabilities) ? typedFrame.capabilities : [];
+						hostCapCache.set(
+							inbound.connectionId,
+							new Set(capabilities.filter((capability): capability is string => typeof capability === "string")),
+						);
+					}
 					inboundSdkFrame?.(inbound.connectionId, typedFrame);
 				} catch {}
 			});
@@ -3748,7 +3843,7 @@ export function createNotificationsExtension(
 				}
 				const gate = runtime?.workflowGate;
 				const workflowGateActive =
-					gate?.isUnattended?.() === true &&
+					gate?.supportsRemoteGateAnswers?.() === true &&
 					typeof gate.onGateEmitted === "function" &&
 					typeof gate.resolveGateFromNotification === "function";
 				const gateId = gatePresentations.routeFor(reply.id);
@@ -4201,7 +4296,9 @@ export function createNotificationsExtension(
 						? Gate
 						: never,
 				): void => {
-					const options = (g.options ?? []).map(o => String((o as { label?: unknown }).label ?? ""));
+					const rawGateOptions = g.options ?? [];
+					const options = rawGateOptions.map(o => String((o as { label?: unknown }).label ?? ""));
+					const recommendedIndex = recommendedIndexFromGateOptions(rawGateOptions);
 					gateOptions.set(g.gate_id, options);
 					const promptCtx = g.context as { prompt?: unknown; title?: unknown } | undefined;
 					const question =
@@ -4218,6 +4315,7 @@ export function createNotificationsExtension(
 						sessionId: id,
 						question,
 						options,
+						...(recommendedIndex === undefined ? {} : { recommendedIndex }),
 						controls: [],
 						multi: stageState.multi === true,
 						allowEmpty: stageState.allow_empty === true,
@@ -4576,22 +4674,45 @@ export function createNotificationsExtension(
 		if (!pending) return;
 		rt.pendingFinal = undefined;
 		if (pending.text && rt.notificationsActive && !rt.redact) {
-			try {
-				pushSessionFrame(rt, {
-					type: "turn_stream",
-					sessionId: id,
-					phase: "finalized",
-					finalAnswer: true,
+			// Under lean, hold intermediate finals until agent_end when the agent is still
+			// running so provisional-policy activation cannot reintroduce per-turn spam.
+			if (rt.verbosity === "lean" && rt.busy) {
+				rt.pendingSettled = {
 					text: pending.text,
 					...(pending.messageRef ? { messageRef: pending.messageRef } : {}),
-				});
-			} catch (error) {
-				logger.warn(`notifications: pushFrame (pending turn) failed: ${String(error)}`);
+				};
+			} else {
+				try {
+					pushSessionFrame(rt, {
+						type: "turn_stream",
+						sessionId: id,
+						phase: "finalized",
+						finalAnswer: true,
+						text: pending.text,
+						...(pending.messageRef ? { messageRef: pending.messageRef } : {}),
+					});
+				} catch (error) {
+					logger.warn(`notifications: pushFrame (pending turn) failed: ${String(error)}`);
+				}
 			}
 		}
 		resetTurnStreamState(rt);
 	};
 
+	/** Emit the deferred lean settled answer exactly once (agent_end / idle). */
+	const flushPendingSettled = (rt: SessionRuntime, id: string): void => {
+		const settled = rt.pendingSettled;
+		rt.pendingSettled = undefined;
+		if (!settled?.text || !rt.notificationsActive || rt.redact || rt.policySuspended) return;
+		const previousLiveRef = rt.liveRef;
+		if (settled.messageRef) rt.liveRef = settled.messageRef;
+		try {
+			flushTurnText(rt, id, settled.text, true);
+		} finally {
+			if (!settled.messageRef) rt.liveRef = previousLiveRef;
+		}
+	};
+
 	// Drive the live typing indicator: mark busy when the agent loop starts so
 	// the daemon shows "typing…" in the thread while the agent is thinking,
 	// before any turn output exists. Cleared on `agent_end` below.
@@ -4604,6 +4725,7 @@ export function createNotificationsExtension(
 		rt.busy = true;
 		const correlation = rt.pendingPromptCorrelations.shift();
 		rt.activePromptCorrelation = correlation;
+		rt.notePromptReconciliation(correlation, { type: "agent_start" });
 		rt.emitPromptLifecycle(correlation, { type: "agent_start", sessionId: id, ...correlation });
 		try {
 			// `activity` is the native live-host lifecycle surface. The separately
@@ -4648,8 +4770,35 @@ export function createNotificationsExtension(
 		rt.busy = false;
 		const correlation = rt.activePromptCorrelation;
 		if (correlation) {
-			if (rt.recordPromptTerminal(correlation))
-				rt.emitPromptLifecycle(correlation, { type: "agent_end", sessionId: id, ...correlation });
+			const terminalAssistant = (Array.isArray(event.messages) ? [...event.messages].reverse() : []).find(
+				message =>
+					message &&
+					typeof message === "object" &&
+					(message as { role?: unknown }).role === "assistant" &&
+					((message as { stopReason?: unknown }).stopReason === "error" ||
+						(message as { stopReason?: unknown }).stopReason === "aborted"),
+			) as { stopReason?: "error" | "aborted"; errorMessage?: unknown } | undefined;
+			const failureCode =
+				event.stopReason === "cancelled"
+					? "cancelled"
+					: terminalAssistant?.stopReason === "error"
+						? "agent_error"
+						: terminalAssistant?.stopReason === "aborted"
+							? "aborted"
+							: undefined;
+			if (failureCode)
+				rt.emitPromptFailure(correlation, {
+					code: failureCode,
+					message:
+						typeof terminalAssistant?.errorMessage === "string"
+							? terminalAssistant.errorMessage
+							: "Prompt submission failed.",
+				});
+			else {
+				rt.notePromptReconciliation(correlation, { type: "agent_end" });
+				if (rt.recordPromptTerminal(correlation))
+					rt.emitPromptLifecycle(correlation, { type: "agent_end", sessionId: id, ...correlation });
+			}
 		} else {
 			rt.emitPromptLifecycle(undefined, { type: "agent_end", sessionId: id });
 		}
@@ -4693,9 +4842,14 @@ export function createNotificationsExtension(
 			logger.warn(`notifications: noteIdle failed: ${String(e)}`);
 		}
 
+		// Lean: emit the latest deferred assistant answer exactly once at idle.
+		// Intermediate tool-turn narration was held on turn_end; ask lead-ins were
+		// already flushed immediately and deduped via preAskFlushedText.
+		flushPendingSettled(rt, id);
+
 		// On idle, stream a context update with metadata (token/model usage +
-		// working-tree diff) unless redaction is on. The agent's last message is
-		// NOT repeated here — it is already streamed once via `turn_stream`.
+		// working-tree diff) unless redaction is on. Under verbose the agent's last
+		// message is already streamed per turn_end; lean flushes it just above.
 		if (!rt.redact && rt.verbosity === "verbose") {
 			const usage = (
 				ctx as { getContextUsage?: () => { tokens: number | null; contextWindow: number } | undefined }
@@ -4724,17 +4878,20 @@ export function createNotificationsExtension(
 		}
 	});
 
-	// Stream viable agent output per turn (the live thread mirror). Unlike idle,
-	// turn output is expected to be multiple messages — one per turn that
-	// produced assistant text. Tool-only turns yield no text and are skipped.
-	// Redaction suppresses streamed content (only the one-time identity header
-	// survives redaction). The daemon coalesces/throttles these via its shared
-	// rate-limit pool before sending to Telegram.
+	// Stream viable agent output. Verbose mirrors each turn that produced assistant
+	// text. Lean defers the latest answer until agent_end (idle) so tool-heavy runs
+	// do not flood remote clients with intermediate narration; ask lead-ins still
+	// flush immediately. Tool-only turns yield no text and are skipped. Redaction
+	// suppresses streamed content (only the one-time identity header survives).
+	// The daemon coalesces/throttles these via its shared rate-limit pool.
 	// Push the in-flight turn's assistant text as a finalized turn_stream, deduped
 	// against what was already flushed for this turn (the pre-ask lead-in).
 	const flushTurnText = (rt: SessionRuntime, id: string, text: string | undefined, finalAnswer: boolean): void => {
 		if (!text || text === rt.preAskFlushedText || !rt.notificationsActive || rt.policySuspended) return;
 		rt.preAskFlushedText = text;
+		// Ask lead-ins supersede any deferred lean settled answer from earlier turns
+		// so agent_end does not re-emit stale intermediate narration (#2863 review).
+		if (!finalAnswer) rt.pendingSettled = undefined;
 		// Decision A: a stream-enabled turn must finalize as an in-place edit of ONE
 		// live message, never a fresh (rich-promotable) send. If live frames were
 		// async-queued and none landed before this flush, reuse the per-turn ref
@@ -4875,19 +5032,37 @@ export function createNotificationsExtension(
 			rt.turnClosed = true;
 			return;
 		}
-		if (text) flushTurnText(rt, id, text, true);
+		if (text) {
+			if (rt.verbosity === "verbose") {
+				// Verbose: one finalized turn_stream per turn with assistant text.
+				flushTurnText(rt, id, text, true);
+			} else if (text !== rt.preAskFlushedText) {
+				// Lean: hold the latest answer until agent_end. Skip when this turn
+				// already flushed the same text as an ask lead-in (no duplicate at idle).
+				rt.pendingSettled = {
+					text,
+					...(rt.liveRef ? { messageRef: rt.liveRef } : {}),
+				};
+			} else {
+				// Lead-in already flushed: drop any older deferred settled text so idle
+				// does not re-emit intermediate narration after the ask prompt (#2863).
+				rt.pendingSettled = undefined;
+			}
+		}
 		resetTurnStreamState(rt);
 	});
 
-	// Live streaming (opt-in): push throttled in-progress assistant text as
-	// non-finalized turn_stream frames so remote clients edit one message as the
-	// turn streams. The finalized frame (turn_end) carries the same messageRef and
-	// lands the authoritative text. Suppressed under redaction.
+	// Live streaming (opt-in + verbose only): push throttled in-progress assistant
+	// text as non-finalized turn_stream frames so remote clients edit one message
+	// as the turn streams. Lean keeps settled-answer-only delivery; live frames
+	// are suppressed even when the stream preference is on. The finalized frame
+	// (turn_end / agent_end) carries the same messageRef and lands the authoritative
+	// text. Suppressed under redaction.
 	api.on("message_update", (event, ctx) => {
 		const id = sessionId(ctx);
 		const rt = runtimes.get(id);
 		rt?.emitPromptEvent(event);
-		if (!rt?.notificationsActive || !rt.stream || rt.redact || rt.turnClosed) return;
+		if (!rt?.notificationsActive || !rt.stream || rt.redact || rt.turnClosed || rt.verbosity !== "verbose") return;
 		if ((event.message as { role?: unknown }).role !== "assistant") return;
 		if (rt.liveRef === undefined && rt.turnSeq !== undefined) {
 			rt.liveRef = String(rt.turnSeq);