@sayknow-cli/coding-agent 0.3.11 → 0.3.13

package/src/notifications/index.ts

@@ -30,8 +30,22 @@ import { NotificationServer } from "@sayknow-cli/natives";
 import { logger, postmortem } from "@sayknow-cli/utils";
 import { Settings } from "../config/settings";
 import type { ExtensionAPI, ExtensionCommandContext, ExtensionContext } from "../extensibility/extensions";
+import type {
+	WorkflowGateEmitter,
+	WorkflowGateTerminalController,
+} from "../modes/shared/agent-wire/unattended-session";
 import { parseThinkingLevel } from "../thinking";
-import { registerAskAnswerSource } from "../tools/ask-answer-registry";
+import type {
+	AskAnswerRequest,
+	AskAnswerSourceResult,
+	AskRemoteControl,
+	AskRemoteInteraction,
+	AskRemoteReceipt,
+	AskSelectedAckOutcome,
+	AskSettlement,
+	AskSettlementResult,
+} from "../tools";
+import { registerAskAnswerSource, registerWorkflowGateEmitterListener } from "../tools/ask-answer-registry";
 import { registerTelegramFileSink } from "./attachment-registry";
 import {
 	getNotificationConfig,
@@ -327,8 +341,128 @@ async function readGitDiffStat(cwd: string): Promise<string | undefined> {
 }
 
 interface PendingInteractiveAsk {
-	resolve: (label: string | undefined) => void;
+	resolve: (result: AskAnswerSourceResult) => void;
 	options: string[];
+	controls: readonly AskRemoteControl[];
+	reissue: () => boolean;
+}
+
+interface UnattendedGatePresentation {
+	gateId: string;
+	sessionId: string;
+	question: string;
+	options: string[];
+	controls: readonly AskRemoteControl[];
+	multi: boolean;
+	allowEmpty: boolean;
+	navigationLabel?: "Next" | "Done";
+	selectedOptions: string[];
+}
+
+/** Keeps transport interaction ids separate from durable workflow gate ids. */
+class GatePresentationRegistry {
+	private readonly presentations = new Map<string, UnattendedGatePresentation>();
+	private readonly routes = new Map<string, string>();
+
+	constructor(
+		private readonly server: NotificationServer,
+		private readonly redact: () => boolean,
+		private readonly tag: string,
+	) {}
+
+	retain(presentation: UnattendedGatePresentation): void {
+		this.presentations.set(presentation.gateId, presentation);
+	}
+
+	routeFor(actionId: string): string | undefined {
+		return this.routes.get(actionId);
+	}
+
+	presentationFor(actionId: string): UnattendedGatePresentation | undefined {
+		const gateId = this.routes.get(actionId);
+		return gateId ? this.presentations.get(gateId) : undefined;
+	}
+
+	toggle(actionId: string, label: string): boolean {
+		const presentation = this.presentationFor(actionId);
+		if (!presentation?.multi || !presentation.options.includes(label)) return false;
+		this.closeInteraction(actionId, "toggle");
+		const selected = new Set(presentation.selectedOptions);
+		if (selected.has(label)) selected.delete(label);
+		else selected.add(label);
+		presentation.selectedOptions = [...selected];
+		this.reissue(presentation.gateId);
+		return true;
+	}
+
+	reissue(gateId: string): string | undefined {
+		const presentation = this.presentations.get(gateId);
+		if (!presentation) return undefined;
+		const actionId = `gate-interaction:${crypto.randomUUID()}`;
+		this.routes.set(actionId, gateId);
+		try {
+			this.server.registerAsk(
+				JSON.stringify(
+					notificationActionPayload(
+						{
+							id: actionId,
+							kind: "ask",
+							sessionId: presentation.sessionId,
+							question:
+								presentation.selectedOptions.length > 0
+									? `(${presentation.selectedOptions.length} selected) ${presentation.question}`
+									: presentation.question,
+							options: presentation.options,
+							controls: presentation.multi
+								? [
+										{
+											id: "navigation_forward",
+											kind: "navigation",
+											label: presentation.navigationLabel ?? "Done",
+											enabled: presentation.allowEmpty || presentation.selectedOptions.length > 0,
+										},
+									]
+								: [],
+						},
+						{ redact: this.redact(), sessionTag: this.tag },
+					),
+				),
+				true,
+			);
+			return actionId;
+		} catch (error) {
+			this.routes.delete(actionId);
+			logger.warn(`notifications: registerAsk (gate interaction) failed: ${String(error)}`);
+			return undefined;
+		}
+	}
+
+	closeInteraction(actionId: string, reason: string): void {
+		this.routes.delete(actionId);
+		try {
+			this.server.resolveLocal(actionId, undefined);
+		} catch {
+			// The native claim close already terminalizes this action when applicable.
+		}
+		void reason;
+	}
+
+	complete(gateId: string): void {
+		for (const [actionId, routeGateId] of this.routes) {
+			if (routeGateId !== gateId) continue;
+			this.closeInteraction(actionId, "gate_complete");
+		}
+		this.presentations.delete(gateId);
+	}
+
+	cancel(gateId: string, reason: string): void {
+		this.complete(gateId);
+		void reason;
+	}
+
+	dispose(): void {
+		for (const gateId of [...this.presentations.keys()]) this.cancel(gateId, "session_shutdown");
+	}
 }
 
 interface SessionRuntime {
@@ -342,6 +476,12 @@ interface SessionRuntime {
 	disposeFileSink: () => void;
 	/** Deregisters this session's unattended workflow-gate listener. */
 	disposeGateListener: () => void;
+	/** Deregisters canonical workflow-gate terminal cleanup. */
+	disposeGateTerminalController: () => void;
+	disposeAckRecoveryParticipant: () => void;
+	disposeGateEmitterListener: () => void;
+	workflowGate?: WorkflowGateEmitter;
+	gatePresentations?: GatePresentationRegistry;
 	redact: boolean;
 	verbosity: "lean" | "verbose";
 	sessionTag: string;
@@ -389,9 +529,11 @@ const defaultConfig: NotificationConfig = {
 	},
 	redact: false,
 	verbosity: "lean",
+	sessionScope: "all",
 	idleTimeoutMs: 60_000,
 	rich: { enabled: true },
 	richDraft: { enabled: false },
+	topics: {},
 };
 
 export function notificationsEnabled(): boolean {
@@ -463,18 +605,41 @@ function mapAnswerToLabel(answerJson: string, options: string[]): string | undef
 	return undefined;
 }
 
-/** Map a client answer to the workflow-gate answer shape (unattended mode). */
-function mapAnswerToGate(
-	answerJson: string,
-	options: string[],
-): { selected: string[]; other?: boolean; custom?: string } {
+/** Workflow-gate answer shape (unattended mode). */
+interface GateAnswer {
+	selected: string[];
+	other?: boolean;
+	custom?: string;
+}
+
+/**
+ * Discriminated result of mapping a client answer to a workflow-gate answer.
+ * `ok: false` means the reply is invalid and the caller must close the exact
+ * claim/receipt and reissue the interaction rather than durably accepting it.
+ */
+type GateAnswerResult = { ok: true; answer: GateAnswer } | { ok: false; reason: string };
+
+/**
+ * Map a client answer to the workflow-gate answer shape (unattended mode).
+ *
+ * The protocol defines a numeric reply as an option index, so a number outside
+ * `options` is invalid (issue #2030): it must NOT be converted into a free-text
+ * `Other` that passes the ask schema and triggers a misleading success ack.
+ * Only JSON strings enter the free-text/Other path.
+ */
+export function mapAnswerToGate(answerJson: string, options: string[]): GateAnswerResult {
 	const answer = parseAnswer(answerJson);
 	if (typeof answer === "number") {
 		const label = options[answer];
-		return label === undefined ? { selected: [], other: true, custom: String(answer) } : { selected: [label] };
+		return label === undefined
+			? { ok: false, reason: "numeric_selector_out_of_range" }
+			: { ok: true, answer: { selected: [label] } };
 	}
 	if (typeof answer === "string") {
-		return options.includes(answer) ? { selected: [answer] } : { selected: [], other: true, custom: answer };
+		return {
+			ok: true,
+			answer: options.includes(answer) ? { selected: [answer] } : { selected: [], other: true, custom: answer },
+		};
 	}
 	if (answer && typeof answer === "object") {
 		const obj = answer as { selected?: unknown; custom?: unknown };
@@ -482,9 +647,9 @@ function mapAnswerToGate(
 			? obj.selected.map(s => (typeof s === "number" ? (options[s] ?? String(s)) : String(s)))
 			: [];
 		const custom = typeof obj.custom === "string" ? obj.custom : undefined;
-		return { selected, other: custom !== undefined, custom };
+		return { ok: true, answer: { selected, other: custom !== undefined, custom } };
 	}
-	return { selected: [] };
+	return { ok: true, answer: { selected: [] } };
 }
 
 interface NotificationControlCommandPayload {
@@ -602,6 +767,92 @@ export async function executeNotificationControlCommand(
 	}
 }
 
+function selectedAckOutcome(value: { status: string; messageId?: number; reason?: string }): AskSelectedAckOutcome {
+	if (value.status === "delivered" && typeof value.messageId === "number") {
+		return { status: "delivered", messageId: value.messageId };
+	}
+	if (value.status === "failed") {
+		switch (value.reason) {
+			case "unsupported":
+			case "no_participant":
+			case "ambiguous_participant":
+			case "route_missing":
+			case "expired":
+			case "cancelled":
+			case "telegram_rejected":
+			case "session_closed":
+				return { status: "failed", reason: value.reason };
+			default:
+				return { status: "failed", reason: "session_closed" };
+		}
+	}
+	switch (value.reason) {
+		case "transport_ambiguous":
+		case "origin_disconnected":
+		case "host_timeout":
+		case "shutdown":
+			return { status: "unknown", reason: value.reason };
+		default:
+			return { status: "unknown", reason: "host_timeout" };
+	}
+}
+
+async function requestLiveSelectedAck(
+	native: {
+		requestAskSelectedAck(
+			replyReceiptId: string,
+			requestJson: string,
+		): Promise<{ status: string; messageId?: number; reason?: string }>;
+	},
+	input: { replyReceiptId: string; actionId: string; commitKey: string; deadlineAt: number },
+): Promise<AskSelectedAckOutcome> {
+	const requestId = `ack:${crypto.randomUUID()}`;
+	try {
+		return selectedAckOutcome(
+			await native.requestAskSelectedAck(
+				input.replyReceiptId,
+				JSON.stringify({
+					mode: "live",
+					requestId,
+					commitKey: input.commitKey,
+					actionId: input.actionId,
+					deadlineAt: input.deadlineAt,
+				}),
+			),
+		);
+	} catch (error) {
+		logger.warn(`notifications: Selected acknowledgement failed: ${String(error)}`);
+		return { status: "unknown", reason: "host_timeout" };
+	}
+}
+
+async function requestRecoveredSelectedAck(
+	native: {
+		requestRecoveredAskSelectedAck(
+			requestJson: string,
+		): Promise<{ status: string; messageId?: number; reason?: string }>;
+	},
+	input: { sessionId: string; actionId: string; commitKey: string; deadlineAt: number },
+): Promise<AskSelectedAckOutcome> {
+	try {
+		return selectedAckOutcome(
+			await native.requestRecoveredAskSelectedAck(
+				JSON.stringify({
+					mode: "recovery",
+					requestId: `ack:${crypto.randomUUID()}`,
+					commitKey: input.commitKey,
+					sessionId: input.sessionId,
+					actionId: input.actionId,
+					deadlineAt: input.deadlineAt,
+				}),
+			),
+		);
+	} catch (error) {
+		logger.warn(`notifications: recovered Selected acknowledgement failed: ${String(error)}`);
+		return { status: "unknown", reason: "host_timeout" };
+	}
+}
+
 /** Register the interactive `ask` answer source for a session (the ask tool
  * races the local UI against a remote reply). Returns the deregister disposer. */
 function registerInteractiveAnswerSource(
@@ -613,29 +864,59 @@ function registerInteractiveAnswerSource(
 ): () => void {
 	return registerAskAnswerSource(id, {
 		awaitAnswer(question, options, signal) {
+			const result = this.awaitAnswerRequest?.({ question, options, interaction: "selector", controls: [] }, signal);
+			if (!result) return Promise.resolve(undefined);
+			return result.then(answer => {
+				if (!answer || typeof answer === "string") return answer;
+				return answer.interaction.kind === "value" ? answer.interaction.value : undefined;
+			});
+		},
+		awaitAnswerRequest(request: AskAnswerRequest, signal?: AbortSignal): Promise<AskAnswerSourceResult> {
 			if (signal?.aborted) return Promise.resolve(undefined);
-			const askId = `ask:${crypto.randomUUID()}`;
-			try {
-				server.registerAsk(
-					JSON.stringify(
-						notificationActionPayload(
-							{ id: askId, kind: "ask", sessionId: id, question, options },
-							{ redact: getRedact(), sessionTag: tag },
+			const register = (askId: string): boolean => {
+				try {
+					server.registerAsk(
+						JSON.stringify(
+							notificationActionPayload(
+								{
+									id: askId,
+									kind: "ask",
+									sessionId: id,
+									question: request.question,
+									options: request.options,
+									controls: request.controls,
+								},
+								{ redact: getRedact(), sessionTag: tag },
+							),
 						),
-					),
-					true,
-				);
-			} catch (e) {
-				logger.warn(`notifications: registerAsk failed: ${String(e)}`);
-				return Promise.resolve(undefined);
-			}
-			return new Promise<string | undefined>(resolve => {
-				pendingInteractive.set(askId, { resolve, options });
+						true,
+					);
+					return true;
+				} catch (error) {
+					logger.warn(`notifications: registerAsk failed: ${String(error)}`);
+					return false;
+				}
+			};
+			let activeAskId = `ask:${crypto.randomUUID()}`;
+			if (!register(activeAskId)) return Promise.resolve(undefined);
+			return new Promise<AskAnswerSourceResult>(resolve => {
+				const pending: PendingInteractiveAsk = {
+					resolve,
+					options: request.options,
+					controls: request.controls,
+					reissue: () => {
+						const nextAskId = `ask:${crypto.randomUUID()}`;
+						if (!register(nextAskId)) return false;
+						activeAskId = nextAskId;
+						pendingInteractive.set(nextAskId, pending);
+						return true;
+					},
+				};
+				pendingInteractive.set(activeAskId, pending);
 				signal?.addEventListener("abort", () => {
-					if (!pendingInteractive.delete(askId)) return;
-					// Local UI answered: mark the remote action resolved-locally.
+					if (!pendingInteractive.delete(activeAskId)) return;
 					try {
-						server.resolveLocal(askId, undefined);
+						server.resolveLocal(activeAskId, undefined);
 					} catch {}
 					resolve(undefined);
 				});
@@ -674,6 +955,16 @@ export function createNotificationsExtension(api: ExtensionAPI, options: { setti
 		try {
 			rt.disposeGateListener();
 		} catch {}
+		try {
+			rt.disposeGateTerminalController();
+		} catch {}
+		try {
+			rt.disposeAckRecoveryParticipant();
+		} catch {}
+		try {
+			rt.disposeGateEmitterListener();
+		} catch {}
+		rt.gatePresentations?.dispose();
 		// Resolve any still-pending interactive asks so the ask tool is not left hanging.
 		for (const pending of rt.pendingInteractive.values()) pending.resolve(undefined);
 		rt.pendingInteractive.clear();
@@ -708,11 +999,6 @@ export function createNotificationsExtension(api: ExtensionAPI, options: { setti
 		if (runtimes.has(id)) return "already";
 
 		const stateRoot = path.join(ctx.cwd, ".skc", "state");
-		const gate = ctx.workflowGate;
-		const unattended =
-			gate?.isUnattended?.() === true &&
-			typeof gate.onGateEmitted === "function" &&
-			typeof gate.resolveGate === "function";
 		const gateOptions = new Map<string, string[]>();
 		const pendingInteractive = new Map<string, PendingInteractiveAsk>();
 		const tag = sessionTag(id);
@@ -723,41 +1009,161 @@ export function createNotificationsExtension(api: ExtensionAPI, options: { setti
 		// The SDK can always answer now (interactive via the answer source, or the
 		// unattended gate), so the endpoint advertises a resolver.
 		const server = new NotificationServer(id, resolveToken(), stateRoot, true);
+		const gatePresentations = new GatePresentationRegistry(server, () => runtime?.redact ?? redact, tag);
 
 		server.onReply((err, reply) => {
 			if (err || !reply) return;
-			// 1) Interactive ask awaiting a remote answer.
+			const native = server as unknown as {
+				resolveClaim(receiptId: string, answerJson?: string, idempotencyKey?: string): void;
+				closeClaimInvalid(receiptId: string, reason: string): void;
+				requestAskSelectedAck(
+					receiptId: string,
+					requestJson: string,
+				): Promise<{ status: string; messageId?: number; reason?: string }>;
+			};
 			const pending = pendingInteractive.get(reply.id);
 			if (pending) {
 				pendingInteractive.delete(reply.id);
-				const label = mapAnswerToLabel(reply.answerJson, pending.options);
+				let interaction: AskRemoteInteraction | undefined;
 				try {
-					server.resolveClient(reply.id, reply.answerJson, reply.idempotencyKey ?? undefined);
-				} catch (e) {
-					logger.warn(`notifications: resolveClient failed: ${String(e)}`);
+					const answer = JSON.parse(reply.answerJson) as unknown;
+					if (typeof answer === "object" && answer && "controlId" in answer) {
+						const controlId = (answer as { controlId?: unknown }).controlId;
+						if (
+							controlId === "navigation_forward" &&
+							pending.controls.some(control => control.id === controlId && control.enabled)
+						) {
+							interaction = { kind: "control", controlId };
+						}
+					} else {
+						const value = mapAnswerToLabel(reply.answerJson, pending.options);
+						if (value !== undefined) interaction = { kind: "value", value };
+					}
+				} catch {}
+				if (!interaction) {
+					try {
+						native.closeClaimInvalid(reply.replyReceiptId, "invalid_answer");
+					} catch {}
+					if (!pending.reissue()) pending.resolve(undefined);
+					return;
 				}
-				pending.resolve(label);
+				let settled: Promise<AskSettlementResult> | undefined;
+				const receipt: AskRemoteReceipt = {
+					source: "remote",
+					interaction,
+					settle(settlement: AskSettlement): Promise<AskSettlementResult> {
+						if (settled) return settled;
+						settled = Promise.resolve().then(async () => {
+							if (settlement.kind === "invalid") {
+								native.closeClaimInvalid(reply.replyReceiptId, settlement.reason);
+								return { kind: "invalid_closed" };
+							}
+							if (settlement.kind === "resolve_without_commit") {
+								native.resolveClaim(reply.replyReceiptId, reply.answerJson, reply.idempotencyKey ?? undefined);
+								return { kind: "resolved_without_commit" };
+							}
+							const ack = await requestLiveSelectedAck(native, {
+								replyReceiptId: reply.replyReceiptId,
+								actionId: reply.id,
+								commitKey: `${reply.id}:${reply.idempotencyKey ?? reply.replyReceiptId}`,
+								deadlineAt: Date.now() + 8_000,
+							});
+							native.resolveClaim(reply.replyReceiptId, reply.answerJson, reply.idempotencyKey ?? undefined);
+							return { kind: "committed", ack };
+						});
+						return settled;
+					},
+				};
+				pending.resolve(receipt);
 				return;
 			}
-			// 2) Unattended workflow gate: resolve the real gate, then confirm.
-			if (unattended && gate?.resolveGate) {
-				const answer = mapAnswerToGate(reply.answerJson, gateOptions.get(reply.id) ?? []);
-				gate
-					.resolveGate({ gate_id: reply.id, answer, idempotency_key: reply.idempotencyKey ?? undefined })
-					.then(() => server.resolveClient(reply.id, reply.answerJson, reply.idempotencyKey ?? undefined))
-					.catch(e => {
-						logger.warn(`notifications: resolveGate failed: ${String(e)}`);
-						try {
-							server.reject(reply.id, "invalid_answer");
-						} catch {}
-					});
+			const gate = runtime?.workflowGate;
+			const unattended =
+				gate?.isUnattended?.() === true &&
+				typeof gate.onGateEmitted === "function" &&
+				typeof gate.resolveGate === "function";
+			const gateId = gatePresentations.routeFor(reply.id);
+			if (unattended && gateId && gate?.resolveGateFromNotification) {
+				const presentation = gatePresentations.presentationFor(reply.id);
+				const rawAnswer = parseAnswer(reply.answerJson);
+				if (presentation?.multi) {
+					const option =
+						typeof rawAnswer === "number"
+							? presentation.options[rawAnswer]
+							: typeof rawAnswer === "string" && presentation.options.includes(rawAnswer)
+								? rawAnswer
+								: undefined;
+					if (option !== undefined) {
+						native.resolveClaim(reply.replyReceiptId, reply.answerJson, reply.idempotencyKey ?? undefined);
+						if (!gatePresentations.toggle(reply.id, option)) gatePresentations.reissue(gateId);
+						return;
+					}
+				}
+				let answer: unknown;
+				if (
+					presentation?.multi &&
+					typeof rawAnswer === "object" &&
+					rawAnswer !== null &&
+					(rawAnswer as { controlId?: unknown }).controlId === "navigation_forward"
+				) {
+					if (!presentation.allowEmpty && presentation.selectedOptions.length === 0) {
+						native.closeClaimInvalid(reply.replyReceiptId, "invalid_control");
+						gatePresentations.closeInteraction(reply.id, "invalid_control");
+						gatePresentations.reissue(gateId);
+						return;
+					}
+					answer = { selected: presentation.selectedOptions };
+				} else if (
+					typeof rawAnswer === "object" &&
+					rawAnswer !== null &&
+					(rawAnswer as { action?: unknown }).action === "clarify"
+				) {
+					answer = rawAnswer;
+				} else if (presentation?.multi && typeof rawAnswer === "string") {
+					answer = { selected: presentation.selectedOptions, other: true, custom: rawAnswer };
+				} else {
+					const mapped = mapAnswerToGate(reply.answerJson, gateOptions.get(gateId) ?? []);
+					if (!mapped.ok) {
+						// A numeric selector outside options is invalid (issue #2030): close the
+						// exact claim/receipt and reissue the interaction — never a success ack.
+						native.closeClaimInvalid(reply.replyReceiptId, mapped.reason);
+						gatePresentations.closeInteraction(reply.id, mapped.reason);
+						gatePresentations.reissue(gateId);
+						return;
+					}
+					answer = mapped.answer;
+				}
+				void gate
+					.resolveGateFromNotification(
+						{ gate_id: gateId, answer, idempotency_key: reply.idempotencyKey ?? undefined },
+						{
+							interactionActionId: reply.id,
+							replyReceiptId: reply.replyReceiptId,
+							answerJson: reply.answerJson,
+							idempotencyKey: reply.idempotencyKey ?? undefined,
+							resolveClaim: () =>
+								native.resolveClaim(reply.replyReceiptId, reply.answerJson, reply.idempotencyKey ?? undefined),
+							closeClaimInvalid: reason => {
+								native.closeClaimInvalid(reply.replyReceiptId, reason);
+								gatePresentations.closeInteraction(reply.id, reason);
+								gatePresentations.reissue(gateId);
+							},
+							requestSelectedAck: input =>
+								requestLiveSelectedAck(native, {
+									replyReceiptId: input.replyReceiptId,
+									actionId: input.actionId,
+									commitKey: input.commitKey,
+									deadlineAt: input.daemonDeadlineAt,
+								}),
+						},
+					)
+					.catch(error => logger.warn(`notifications: resolveGateFromNotification failed: ${String(error)}`));
 				return;
 			}
-			// 3) No matching pending ask.
 			try {
-				server.reject(reply.id, "unknown_action");
-			} catch (e) {
-				logger.warn(`notifications: reject failed: ${String(e)}`);
+				server.closeClaimInvalid(reply.replyReceiptId, "unknown_action");
+			} catch (error) {
+				logger.warn(`notifications: closeClaimInvalid failed: ${String(error)}`);
 			}
 		});
 
@@ -892,6 +1298,11 @@ export function createNotificationsExtension(api: ExtensionAPI, options: { setti
 				disposeAnswerSource,
 				disposeFileSink,
 				disposeGateListener: () => {},
+				disposeGateTerminalController: () => {},
+				disposeAckRecoveryParticipant: () => {},
+				disposeGateEmitterListener: () => {},
+				workflowGate: undefined,
+				gatePresentations,
 				cancelPostmortemCleanup: () => {},
 				redact,
 				verbosity,
@@ -901,6 +1312,7 @@ export function createNotificationsExtension(api: ExtensionAPI, options: { setti
 				pendingInbound: new Set<number>(),
 			};
 			runtimes.set(id, runtime);
+			const activeRuntime = runtime;
 			// A native terminal close (SIGHUP), SIGTERM, Ctrl+C exit, or fatal error
 			// skips AgentSession.dispose(), so the `session_shutdown` extension event
 			// never fires and the daemon-side topic would be orphaned. postmortem
@@ -910,7 +1322,7 @@ export function createNotificationsExtension(api: ExtensionAPI, options: { setti
 			runtime.cancelPostmortemCleanup = postmortem.register(`notifications-session-closed:${id}`, async () => {
 				await stopSession(id);
 			});
-			logger.info(`notifications: serving session ${id} at ${endpoint.url} (unattended=${unattended})`);
+			logger.info(`notifications: serving session ${id} at ${endpoint.url}`);
 
 			if (settingsAvailable && settings && isTelegramConfigured(cfg)) {
 				try {
@@ -934,9 +1346,35 @@ export function createNotificationsExtension(api: ExtensionAPI, options: { setti
 				logger.warn(`notifications: identity_header failed: ${String(e)}`);
 			}
 
-			// Unattended: a real ask emits a workflow gate; register it repliable by gate_id.
-			if (unattended && gate?.onGateEmitted) {
-				runtime.disposeGateListener = gate.onGateEmitted(g => {
+			// Workflow-gate installation occurs after session_start in RPC/bridge modes.
+			// Attach dynamically so those sessions receive the same Telegram gate surface.
+			const attachWorkflowGate = (gate: WorkflowGateEmitter | undefined): void => {
+				if (activeRuntime.workflowGate === gate) return;
+				activeRuntime.disposeGateListener();
+				activeRuntime.disposeGateTerminalController();
+				activeRuntime.disposeAckRecoveryParticipant();
+				activeRuntime.disposeGateListener = () => {};
+				activeRuntime.disposeGateTerminalController = () => {};
+				activeRuntime.disposeAckRecoveryParticipant = () => {};
+				activeRuntime.workflowGate = undefined;
+				gateOptions.clear();
+				gatePresentations.dispose();
+				if (typeof gate?.onGateEmitted !== "function" || typeof gate.resolveGate !== "function") {
+					return;
+				}
+				activeRuntime.workflowGate = gate;
+				if (gate.registerGateTerminalController) {
+					const controller: WorkflowGateTerminalController = {
+						completeGateInteractions: gateId => gatePresentations.complete(gateId),
+						cancelGateInteractions: (gateId, reason) => gatePresentations.cancel(gateId, reason),
+					};
+					try {
+						activeRuntime.disposeGateTerminalController = gate.registerGateTerminalController(controller);
+					} catch (error) {
+						logger.warn(`notifications: gate terminal controller unavailable: ${String(error)}`);
+					}
+				}
+				activeRuntime.disposeGateListener = gate.onGateEmitted(g => {
 					const options = (g.options ?? []).map(o => String((o as { label?: unknown }).label ?? ""));
 					gateOptions.set(g.gate_id, options);
 					const promptCtx = g.context as { prompt?: unknown; title?: unknown } | undefined;
@@ -944,21 +1382,43 @@ export function createNotificationsExtension(api: ExtensionAPI, options: { setti
 						(typeof promptCtx?.prompt === "string" && promptCtx.prompt) ||
 						(typeof promptCtx?.title === "string" && promptCtx.title) ||
 						"Question";
-					try {
-						server.registerAsk(
-							JSON.stringify(
-								notificationActionPayload(
-									{ id: g.gate_id, kind: "ask", sessionId: id, question, options },
-									{ redact, sessionTag: tag },
-								),
-							),
-							true,
-						);
-					} catch (e) {
-						logger.warn(`notifications: registerAsk (gate) failed: ${String(e)}`);
-					}
+					const stageState =
+						typeof g.context?.stage_state === "object" && g.context.stage_state !== null
+							? (g.context.stage_state as Record<string, unknown>)
+							: {};
+					gatePresentations.retain({
+						gateId: g.gate_id,
+						sessionId: id,
+						question,
+						options,
+						controls: [],
+						multi: stageState.multi === true,
+						allowEmpty: stageState.allow_empty === true,
+						navigationLabel: stageState.navigation_label === "Next" ? "Next" : "Done",
+						selectedOptions: [],
+					});
+					gatePresentations.reissue(g.gate_id);
 				});
-			}
+				if (gate.setAckRecoveryParticipant) {
+					const native = server as unknown as {
+						requestRecoveredAskSelectedAck(
+							requestJson: string,
+						): Promise<{ status: string; messageId?: number; reason?: string }>;
+					};
+					gate.setAckRecoveryParticipant({
+						requestRecoveredAskSelectedAck: input =>
+							requestRecoveredSelectedAck(native, {
+								sessionId: input.sessionId,
+								actionId: input.actionId,
+								commitKey: input.commitKey,
+								deadlineAt: input.deadlineAt,
+							}),
+					});
+					activeRuntime.disposeAckRecoveryParticipant = () => gate.setAckRecoveryParticipant?.(null);
+				}
+			};
+			activeRuntime.disposeGateEmitterListener = registerWorkflowGateEmitterListener(id, attachWorkflowGate);
+			if (ctx.workflowGate) attachWorkflowGate(ctx.workflowGate);
 			return "started";
 		} catch (e) {
 			logger.warn(`notifications: failed to start server: ${String(e)}`);