@sayknow-cli/coding-agent 0.3.12 → 0.3.15

package/src/modes/shared/agent-wire/deep-interview-gate.ts

@@ -44,6 +44,8 @@ export interface AskGateQuestion {
 	deepInterview?: AskGateDeepInterviewState;
 	/** Override the emitted workflow gate address for non-deep-interview ask prompts. */
 	workflowGate?: AskGateWorkflowGateMeta;
+	allowEmpty?: boolean;
+	navigationLabel?: "Next" | "Done";
 }
 
 export interface AskGateResult {
@@ -119,7 +121,7 @@ function questionAnswerSchema(question: AskGateQuestion, labels: string[]): RpcJ
 	const selectedBase: RpcJsonSchema = { type: "array", items: selectedItems, uniqueItems: true };
 	const selectedOnly: RpcJsonSchema = {
 		...selectedBase,
-		minItems: 1,
+		minItems: question.allowEmpty ? 0 : 1,
 		...(multi ? {} : { maxItems: 1 }),
 	};
 	const selectedWithOther: RpcJsonSchema = {
@@ -216,6 +218,8 @@ export function questionToGate(question: AskGateQuestion): OpenGateInput {
 				options: labels,
 				other_option: GATE_OTHER_OPTION,
 				clarification_action: "clarify",
+				allow_empty: question.allowEmpty === true,
+				navigation_label: question.navigationLabel,
 				...(question.deepInterview
 					? structuredDeepInterviewState(question.deepInterview)
 					: deepInterviewQuestionState(question.question)),
@@ -280,12 +284,21 @@ export function gateAnswerToResult(question: AskGateQuestion, answer: unknown):
 	}
 	const other = answer.other === true;
 	const totalPicks = deduped.length + (other ? 1 : 0);
-	if (totalPicks === 0) {
+	if (totalPicks === 0 && !question.allowEmpty) {
 		throw new DeepInterviewGateError(
 			"empty_selection",
 			"at least one option (or the free-text other) must be selected",
 		);
 	}
+	if (totalPicks === 0) {
+		return {
+			id: question.id,
+			question: question.question,
+			options: labels,
+			multi,
+			selectedOptions: [],
+		};
+	}
 	if (!multi && totalPicks > 1) {
 		throw new DeepInterviewGateError("multi_not_allowed", "this question accepts a single selection");
 	}
@@ -302,6 +315,36 @@ export function gateAnswerToResult(question: AskGateQuestion, answer: unknown):
 	};
 }
 
+/**
+ * Classify an accepted ask-domain gate answer independently of its transport.
+ * Schema-invalid and semantically invalid answers throw, so callers leave the
+ * durable gate pending rather than treating them as a non-committing answer.
+ */
+export function classifyAskGateDisposition(
+	gate: Pick<OpenGateInput, "context" | "options">,
+	answer: unknown,
+): "commit" | "resolve_without_commit" {
+	const state = gate.context?.stage_state;
+	if (typeof state !== "object" || state === null) return "commit";
+	const questionId = (state as Record<string, unknown>).question_id;
+	if (typeof questionId !== "string") return "commit";
+	const question: AskGateQuestion = {
+		id: questionId,
+		question: typeof gate.context?.prompt === "string" ? gate.context.prompt : questionId,
+		options: (gate.options ?? []).map(option => ({
+			label: typeof option.value === "string" ? option.value : option.label,
+		})),
+		multi: (state as Record<string, unknown>).multi === true,
+		allowEmpty: (state as Record<string, unknown>).allow_empty === true,
+	};
+	if (typeof answer === "object" && answer !== null && (answer as Record<string, unknown>).action === "clarify") {
+		gateAnswerToResult(question, answer);
+		return "resolve_without_commit";
+	}
+	const result = gateAnswerToResult(question, answer);
+	return result.selectedOptions.length === 0 && result.customInput === undefined ? "resolve_without_commit" : "commit";
+}
+
 /** Convenience: map a batch of ask questions to gate open-inputs. */
 export function questionsToGates(questions: AskGateQuestion[]): OpenGateInput[] {
 	return questions.map(questionToGate);

package/src/modes/shared/agent-wire/scopes.ts

@@ -49,6 +49,7 @@ const RPC_COMMAND_SCOPE_REGISTRY: Record<RpcCommandType, BridgeCommandScope> = {
 	get_pending_workflow_gates: "message:read",
 	set_capabilities: "control",
 	set_model: "model",
+	set_default_model_selection: "model",
 	cycle_model: "model",
 	get_available_models: "model",
 	set_thinking_level: "model",

package/src/modes/shared/agent-wire/unattended-session.ts

@@ -15,6 +15,7 @@
  * RPC server can route `negotiate_unattended` + `workflow_gate_response` here.
  */
 import type { Model } from "@sayknow-cli/ai";
+import type { AskSelectedAckOutcome } from "../../../tools";
 import type {
 	RpcCommand,
 	RpcUnattendedAccepted,
@@ -30,7 +31,53 @@ import {
 	type UnattendedAuditEvent,
 	UnattendedRunController,
 } from "./unattended-run-controller";
-import { type GateStore, MemoryGateStore, type OpenGateInput, WorkflowGateBroker } from "./workflow-gate-broker";
+import {
+	type GateStore,
+	MemoryGateStore,
+	type OpenGateInput,
+	type PersistedAckPolicy,
+	type PersistedGate,
+	type PersistedSemanticDisposition,
+	WorkflowGateBroker,
+} from "./workflow-gate-broker";
+
+export interface WorkflowGateTerminalController {
+	completeGateInteractions(gateId: string): void | Promise<void>;
+	cancelGateInteractions(gateId: string, reason: string): void | Promise<void>;
+}
+
+export interface WorkflowGateTerminalEvent {
+	gateId: string;
+	kind: "accepted" | "cancelled";
+	origin?: "rpc" | "bridge" | "other" | "telegram_notification";
+	reason?: string;
+}
+
+export interface NotificationGateResolutionOptions {
+	interactionActionId: string;
+	replyReceiptId: string;
+	answerJson: string;
+	idempotencyKey?: string;
+	requestSelectedAck(input: {
+		replyReceiptId: string;
+		actionId: string;
+		commitKey: string;
+		daemonDeadlineAt: number;
+		hostTimeoutMs: number;
+	}): Promise<AskSelectedAckOutcome>;
+	resolveClaim(): void;
+	closeClaimInvalid(reason: string): void;
+}
+
+export interface AskSelectedAckRecoveryParticipant {
+	requestRecoveredAskSelectedAck(input: {
+		sessionId: string;
+		actionId: string;
+		commitKey: string;
+		deadlineAt: number;
+		hostTimeoutMs: number;
+	}): Promise<AskSelectedAckOutcome>;
+}
 
 /**
  * RPC commands that perform agent/tool work and therefore consume one unit of the
@@ -66,7 +113,13 @@ export interface WorkflowGateEmitter {
 	 */
 	onGateEmitted?(listener: (gate: RpcWorkflowGate) => void): () => void;
 	resolveGate?(response: RpcWorkflowGateResponse): Promise<RpcWorkflowGateResolution>;
+	resolveGateFromNotification?(
+		response: RpcWorkflowGateResponse,
+		options: NotificationGateResolutionOptions,
+	): Promise<RpcWorkflowGateResolution>;
+	registerGateTerminalController?(controller: WorkflowGateTerminalController): () => void;
 	listPendingGates?(): RpcWorkflowGate[];
+	setAckRecoveryParticipant?(participant: AskSelectedAckRecoveryParticipant | null): void;
 }
 
 export interface UnattendedSessionOptions {
@@ -91,6 +144,12 @@ export class UnattendedSessionControlPlane implements RpcUnattendedControlPlane,
 	readonly #pending = new Map<string, { resolve: (answer: unknown) => void; reject: (err: Error) => void }>();
 	readonly #earlyAnswers = new Map<string, unknown>();
 	readonly #gateListeners = new Set<(gate: RpcWorkflowGate) => void>();
+	#terminalController: WorkflowGateTerminalController | undefined;
+	#brokerReady = false;
+	#recoveryPromise: Promise<void> | undefined;
+	#disposed = false;
+	#recoveryParticipant: AskSelectedAckRecoveryParticipant | undefined;
+	#participantReady = Promise.withResolvers<void>();
 
 	constructor(private readonly opts: UnattendedSessionOptions) {}
 
@@ -108,6 +167,38 @@ export class UnattendedSessionControlPlane implements RpcUnattendedControlPlane,
 		return this.#controller;
 	}
 
+	registerGateTerminalController(controller: WorkflowGateTerminalController): () => void {
+		if (this.#terminalController && this.#terminalController !== controller) {
+			throw new Error("a workflow gate terminal controller is already registered");
+		}
+		this.#terminalController = controller;
+		return () => {
+			if (this.#terminalController === controller) this.#terminalController = undefined;
+		};
+	}
+
+	setAckRecoveryParticipant(participant: AskSelectedAckRecoveryParticipant | null): void {
+		this.#recoveryParticipant = participant ?? undefined;
+		if (participant) this.#participantReady.resolve();
+		void this.startRecoveryOnce();
+	}
+
+	async #completeGateInteractions(gateId: string): Promise<void> {
+		try {
+			await this.#terminalController?.completeGateInteractions(gateId);
+		} catch (error) {
+			this.opts.audit?.({ event: "gate_interaction_completion_failed", gate_id: gateId, error: String(error) });
+		}
+	}
+
+	async #cancelGateInteractions(gateId: string, reason: string): Promise<void> {
+		try {
+			await this.#terminalController?.cancelGateInteractions(gateId, reason);
+		} catch (error) {
+			this.opts.audit?.({ event: "gate_interaction_cancellation_failed", gate_id: gateId, error: String(error) });
+		}
+	}
+
 	negotiate(declaration: RpcUnattendedDeclaration): RpcUnattendedAccepted {
 		const controller = UnattendedRunController.negotiate(declaration, {
 			runId: this.opts.runId,
@@ -140,7 +231,11 @@ export class UnattendedSessionControlPlane implements RpcUnattendedControlPlane,
 				// openGate returns and the caller starts awaiting.
 				this.#earlyAnswers.set(gate.gate_id, answer);
 			},
+			finalizeAccepted: record => this.#finalizeAcceptedGate(record),
 		});
+		this.#brokerReady = true;
+		void this.startRecoveryOnce();
+
 		return {
 			run_id: this.opts.runId,
 			actor: controller.actor,
@@ -190,12 +285,203 @@ export class UnattendedSessionControlPlane implements RpcUnattendedControlPlane,
 	}
 
 	resolveGate(response: RpcWorkflowGateResponse): Promise<RpcWorkflowGateResolution> {
+		if (this.#disposed) return Promise.reject(new Error("unattended session is disposed"));
 		if (!this.#broker) {
 			return Promise.reject(new Error("workflow gates are not available until unattended mode is negotiated"));
 		}
 		return this.#broker.resolve(response);
 	}
 
+	async resolveGateFromNotification(
+		response: RpcWorkflowGateResponse,
+		options: NotificationGateResolutionOptions,
+	): Promise<RpcWorkflowGateResolution> {
+		let claimSettled = false;
+		const resolveClaim = () => {
+			if (claimSettled) return;
+			claimSettled = true;
+			try {
+				options.resolveClaim();
+			} catch (error) {
+				this.opts.audit?.({
+					event: "notification_claim_resolution_failed",
+					gate_id: response.gate_id,
+					error: String(error),
+				});
+			}
+		};
+		const closeClaimInvalid = (reason: string) => {
+			if (claimSettled) return;
+			claimSettled = true;
+			try {
+				options.closeClaimInvalid(reason);
+			} catch (error) {
+				this.opts.audit?.({
+					event: "notification_claim_close_failed",
+					gate_id: response.gate_id,
+					error: String(error),
+				});
+			}
+		};
+		if (this.#disposed) {
+			closeClaimInvalid("unattended_session_disposed");
+			throw new Error("unattended session is disposed");
+		}
+		if (!this.#broker) {
+			closeClaimInvalid("workflow_gate_unavailable");
+			throw new Error("workflow gates are not available until unattended mode is negotiated");
+		}
+		try {
+			JSON.parse(options.answerJson);
+		} catch {
+			closeClaimInvalid("invalid_structured_answer");
+			return {
+				gate_id: response.gate_id,
+				status: "rejected",
+				answer_hash: "",
+				resolved_at: new Date().toISOString(),
+				error: this.#broker.validationError(response.gate_id, "json_parse", "invalid structured answer"),
+			};
+		}
+		let disposition: PersistedSemanticDisposition;
+		try {
+			disposition = this.#broker.classifyDisposition(response.gate_id, response.answer);
+		} catch (error) {
+			closeClaimInvalid(error instanceof Error ? error.message : "invalid_answer");
+			return {
+				gate_id: response.gate_id,
+				status: "rejected",
+				answer_hash: "",
+				resolved_at: new Date().toISOString(),
+				error: this.#broker.validationError(
+					response.gate_id,
+					"semantic_disposition",
+					error instanceof Error ? error.message : "invalid answer",
+				),
+			};
+		}
+
+		const commitKey = `${response.gate_id}:${options.idempotencyKey ?? options.replyReceiptId}`;
+		const ackPolicy: PersistedAckPolicy =
+			disposition === "commit"
+				? {
+						kind: "telegram_selected_v1",
+						commitKey,
+						actionId: options.interactionActionId,
+						state: "pending",
+						updatedAt: new Date().toISOString(),
+					}
+				: { kind: "none", reason: "semantic_noncommit" };
+		let resolution: RpcWorkflowGateResolution;
+		try {
+			resolution = await this.#broker.resolve(response, {
+				resolutionOrigin: { kind: "telegram_notification", interactionActionId: options.interactionActionId },
+				ackPolicy,
+				semanticDisposition: disposition,
+
+				beforeAdvance: async () => {
+					if (ackPolicy.kind === "telegram_selected_v1") {
+						this.#broker?.updateAckPolicy(response.gate_id, {
+							...ackPolicy,
+							state: "attempt_started",
+							updatedAt: new Date().toISOString(),
+						});
+						let outcome: AskSelectedAckOutcome;
+						try {
+							outcome = await options.requestSelectedAck({
+								replyReceiptId: options.replyReceiptId,
+								actionId: options.interactionActionId,
+								commitKey,
+								daemonDeadlineAt: Date.now() + 8_000,
+								hostTimeoutMs: 10_000,
+							});
+						} catch {
+							outcome = { status: "unknown", reason: "host_timeout" };
+						}
+						this.#broker?.updateAckPolicy(response.gate_id, {
+							...ackPolicy,
+							state: outcome.status,
+							outcome,
+							updatedAt: new Date().toISOString(),
+						});
+					}
+					resolveClaim();
+				},
+			});
+		} catch (error) {
+			closeClaimInvalid(error instanceof Error ? error.message : "invalid_answer");
+			throw error;
+		}
+		if (resolution.status === "accepted") resolveClaim();
+		else closeClaimInvalid(resolution.error?.code ?? "invalid_answer");
+		return resolution;
+	}
+
+	async startRecoveryOnce(options: { participantGraceMs?: number } = {}): Promise<void> {
+		if (this.#disposed || !this.#brokerReady) return;
+		if (this.#recoveryPromise) return this.#recoveryPromise;
+		this.#recoveryPromise = (async () => {
+			if (!this.#recoveryParticipant) {
+				const grace = options.participantGraceMs ?? 2_000;
+				await Promise.race([
+					this.#participantReady.promise,
+					new Promise<void>(resolve => setTimeout(resolve, grace)),
+				]);
+			}
+			if (!this.#disposed) await this.#broker?.recover();
+		})();
+		return this.#recoveryPromise;
+	}
+
+	async #finalizeAcceptedGate(record: PersistedGate): Promise<void> {
+		const policy = record.ackPolicy;
+		if (policy?.kind === "telegram_selected_v1" && policy.state === "pending") {
+			let outcome: AskSelectedAckOutcome;
+			const participant = this.#recoveryParticipant;
+			if (!participant || !this.opts.sessionId) {
+				outcome = { status: "failed", reason: "no_participant" };
+			} else {
+				this.#broker?.updateAckPolicy(record.gate.gate_id, {
+					...policy,
+					state: "attempt_started",
+					updatedAt: new Date().toISOString(),
+				});
+				try {
+					outcome = await participant.requestRecoveredAskSelectedAck({
+						sessionId: this.opts.sessionId,
+						actionId: policy.actionId,
+						commitKey: policy.commitKey,
+						deadlineAt: Date.now() + 8_000,
+						hostTimeoutMs: 10_000,
+					});
+				} catch {
+					outcome = { status: "unknown", reason: "host_timeout" };
+				}
+			}
+			this.#broker?.updateAckPolicy(record.gate.gate_id, {
+				...policy,
+				state: outcome.status,
+				outcome,
+				updatedAt: new Date().toISOString(),
+			});
+		}
+		if (policy?.kind === "telegram_selected_v1" && policy.state === "attempt_started") {
+			this.#broker?.updateAckPolicy(record.gate.gate_id, {
+				...policy,
+				state: "unknown",
+				outcome: { status: "unknown", reason: "shutdown" },
+				updatedAt: new Date().toISOString(),
+			});
+		}
+		await this.#completeGateInteractions(record.gate.gate_id);
+	}
+
+	dispose(reason = "session_shutdown"): void {
+		this.#disposed = true;
+		for (const gateId of this.#pending.keys()) void this.#cancelGateInteractions(gateId, reason);
+		this.#rejectAllPending(new Error(`unattended session disposed: ${reason}`));
+	}
+
 	listPendingGates(): import("../../rpc/rpc-types").RpcWorkflowGate[] {
 		const store = this.opts.store;
 		if (!store) return [];
@@ -206,6 +492,7 @@ export class UnattendedSessionControlPlane implements RpcUnattendedControlPlane,
 	}
 
 	emitGate(input: OpenGateInput): Promise<unknown> {
+		if (this.#disposed) return Promise.reject(new Error("unattended session is disposed"));
 		if (!this.#broker) {
 			return Promise.reject(new Error("cannot emit a workflow gate before unattended mode is negotiated"));
 		}

package/src/modes/shared/agent-wire/workflow-gate-broker.ts

@@ -13,6 +13,7 @@
  */
 import { closeSync, fsyncSync, mkdirSync, openSync, readFileSync, renameSync, writeFileSync } from "node:fs";
 import * as path from "node:path";
+import type { AskSelectedAckOutcome } from "../../../tools";
 import type {
 	RpcWorkflowGate,
 	RpcWorkflowGateContext,
@@ -20,11 +21,36 @@ import type {
 	RpcWorkflowGateOption,
 	RpcWorkflowGateResolution,
 	RpcWorkflowGateResponse,
+	RpcWorkflowGateValidationError,
 	RpcWorkflowStage,
 } from "../../rpc/rpc-types";
 import { RESERVED_WORKFLOW_STAGES } from "../../rpc/rpc-types";
+import { classifyAskGateDisposition } from "./deep-interview-gate";
 import { answerHashOf, canonicalJson, compileGateSchema, schemaHash, validateGateAnswer } from "./workflow-gate-schema";
 
+export type PersistedSemanticDisposition = "commit" | "resolve_without_commit";
+export type PersistedResolutionOrigin =
+	| { kind: "generic"; channel: "rpc" | "bridge" | "other" }
+	| { kind: "telegram_notification"; interactionActionId: string }
+	| { kind: "legacy_unknown" };
+export type PersistedAckPolicy =
+	| { kind: "none"; reason: "non_telegram" | "semantic_noncommit" | "legacy_unproven" }
+	| {
+			kind: "telegram_selected_v1";
+			commitKey: string;
+			actionId: string;
+			state: "pending" | "attempt_started" | "delivered" | "failed" | "unknown";
+			outcome?: AskSelectedAckOutcome;
+			updatedAt: string;
+	  };
+
+export interface GateResolutionOptions {
+	semanticDisposition?: PersistedSemanticDisposition;
+	resolutionOrigin?: PersistedResolutionOrigin;
+	ackPolicy?: PersistedAckPolicy;
+	beforeAdvance?: () => Promise<void>;
+}
+
 const V1_STAGES: readonly RpcWorkflowStage[] = ["deep-interview", "ralplan", "ultragoal"];
 
 export interface PersistedGate {
@@ -36,6 +62,9 @@ export interface PersistedGate {
 	answer?: unknown;
 	resolution?: RpcWorkflowGateResolution;
 	advanced: boolean;
+	semanticDisposition?: PersistedSemanticDisposition;
+	resolutionOrigin?: PersistedResolutionOrigin;
+	ackPolicy?: PersistedAckPolicy;
 }
 
 export interface GateStore {
@@ -153,6 +182,9 @@ export interface BrokerHooks {
 	 * it for any gate left `accepted` but not `advanced` by a crash.
 	 */
 	advance?(gate: RpcWorkflowGate, answer: unknown): void | Promise<void>;
+	/** Runs after durable acceptance and before advance, including crash recovery. */
+	finalizeAccepted?(record: PersistedGate): Promise<void>;
+
 	/** Append-only audit sink. */
 	audit?(event: GateAuditEvent): void;
 }
@@ -176,12 +208,51 @@ export class WorkflowGateBrokerError extends Error {
 }
 
 export class WorkflowGateBroker {
+	private readonly recovering = new Set<string>();
+	private readonly gateLocks = new Map<string, Promise<void>>();
+
+	private async withGateLock<T>(gateId: string, operation: () => Promise<T>): Promise<T> {
+		const previous = this.gateLocks.get(gateId) ?? Promise.resolve();
+		const release = Promise.withResolvers<void>();
+		const current = previous.then(() => release.promise);
+		this.gateLocks.set(gateId, current);
+		await previous;
+		try {
+			return await operation();
+		} finally {
+			release.resolve();
+			if (this.gateLocks.get(gateId) === current) this.gateLocks.delete(gateId);
+		}
+	}
+
 	constructor(
 		private readonly runId: string,
 		private readonly store: GateStore,
 		private readonly hooks: BrokerHooks = {},
 	) {}
 
+	classifyDisposition(gateId: string, answer: unknown): PersistedSemanticDisposition {
+		const record = this.store.get(gateId);
+		if (!record) throw new WorkflowGateBrokerError("unknown_gate", `no pending gate ${gateId}`);
+		return classifyAskGateDisposition(record.gate, answer);
+	}
+	validationError(gateId: string, keyword: string, message: string): RpcWorkflowGateValidationError {
+		const record = this.store.get(gateId);
+		return {
+			code: "invalid_workflow_gate_answer",
+			gate_id: gateId,
+			schema_hash: record ? schemaHash(record.gate.schema) : "",
+			errors: [{ path: "$", keyword, message }],
+		};
+	}
+
+	updateAckPolicy(gateId: string, ackPolicy: PersistedAckPolicy): void {
+		const record = this.store.get(gateId);
+		if (record?.status !== "accepted")
+			throw new WorkflowGateBrokerError("unknown_gate", `no accepted gate ${gateId}`);
+		this.store.put({ ...record, ackPolicy });
+	}
+
 	private runShort(): string {
 		return this.runId.replace(/[^a-zA-Z0-9]/g, "").slice(-8) || "run";
 	}
@@ -222,7 +293,17 @@ export class WorkflowGateBroker {
 	 * On success the resolution is persisted BEFORE `advance` is invoked exactly
 	 * once. Invalid answers leave the gate pending (per #315 acceptance).
 	 */
-	async resolve(response: RpcWorkflowGateResponse): Promise<RpcWorkflowGateResolution> {
+	async resolve(
+		response: RpcWorkflowGateResponse,
+		options: GateResolutionOptions = {},
+	): Promise<RpcWorkflowGateResolution> {
+		return this.withGateLock(response.gate_id, () => this.resolveUnlocked(response, options));
+	}
+
+	private async resolveUnlocked(
+		response: RpcWorkflowGateResponse,
+		options: GateResolutionOptions = {},
+	): Promise<RpcWorkflowGateResolution> {
 		const record = this.store.get(response.gate_id);
 		if (!record) {
 			this.hooks.audit?.({ event: "gate_response_unknown_gate", gate_id: response.gate_id });
@@ -263,6 +344,13 @@ export class WorkflowGateBroker {
 			};
 		}
 
+		const semanticDisposition =
+			options.semanticDisposition ?? classifyAskGateDisposition(record.gate, response.answer);
+		const resolutionOrigin = options.resolutionOrigin ?? { kind: "generic", channel: "rpc" as const };
+		const ackPolicy =
+			options.ackPolicy ??
+			({ kind: "none", reason: semanticDisposition === "commit" ? "non_telegram" : "semantic_noncommit" } as const);
+
 		const resolution: RpcWorkflowGateResolution = {
 			gate_id: response.gate_id,
 			status: "accepted",
@@ -280,18 +368,30 @@ export class WorkflowGateBroker {
 			answer: response.answer,
 			resolution,
 			advanced: false,
+			semanticDisposition,
+			resolutionOrigin,
+			ackPolicy,
 		});
 		this.hooks.audit?.({ event: "gate_response_accepted", gate_id: response.gate_id, answer_hash: answerHash });
-		await this.hooks.advance?.(record.gate, response.answer);
-		this.store.put({
-			gate: record.gate,
-			status: "accepted",
-			idempotencyKey: response.idempotency_key,
-			responseHash,
-			answer: response.answer,
-			resolution,
-			advanced: true,
-		});
+		await options.beforeAdvance?.();
+		await this.hooks.finalizeAccepted?.(this.store.get(response.gate_id) as PersistedGate);
+		const finalized = this.store.get(response.gate_id);
+		if (finalized?.status !== "accepted") {
+			throw new WorkflowGateBrokerError(
+				"unknown_gate",
+				`accepted gate ${response.gate_id} disappeared before advance`,
+			);
+		}
+		if (finalized.advanced) return finalized.resolution ?? resolution;
+		await this.hooks.advance?.(finalized.gate, finalized.answer);
+		const latest = this.store.get(response.gate_id);
+		if (latest?.status !== "accepted") {
+			throw new WorkflowGateBrokerError(
+				"unknown_gate",
+				`accepted gate ${response.gate_id} disappeared after advance`,
+			);
+		}
+		this.store.put({ ...latest, advanced: true });
 		return resolution;
 	}
 
@@ -304,15 +404,25 @@ export class WorkflowGateBroker {
 	async recover(): Promise<string[]> {
 		const recovered: string[] = [];
 		for (const listed of this.store.list()) {
-			if (listed.status !== "accepted" || listed.advanced) continue;
-			// Re-read immediately before advancing so a concurrent recoverer that
-			// already advanced this gate (stale snapshot) cannot double-advance.
-			const rec = this.store.get(listed.gate.gate_id);
-			if (rec?.status !== "accepted" || rec.advanced) continue;
-			await this.hooks.advance?.(rec.gate, rec.answer);
-			this.store.put({ ...rec, advanced: true });
-			this.hooks.audit?.({ event: "gate_advance_recovered", gate_id: rec.gate.gate_id });
-			recovered.push(rec.gate.gate_id);
+			if (listed.status !== "accepted" || listed.advanced || this.recovering.has(listed.gate.gate_id)) continue;
+			this.recovering.add(listed.gate.gate_id);
+			try {
+				await this.withGateLock(listed.gate.gate_id, async () => {
+					const rec = this.store.get(listed.gate.gate_id);
+					if (rec?.status !== "accepted" || rec.advanced) return;
+					await this.hooks.finalizeAccepted?.(rec);
+					const finalized = this.store.get(listed.gate.gate_id);
+					if (finalized?.status !== "accepted" || finalized.advanced) return;
+					await this.hooks.advance?.(finalized.gate, finalized.answer);
+					const latest = this.store.get(listed.gate.gate_id);
+					if (latest?.status !== "accepted" || latest.advanced) return;
+					this.store.put({ ...latest, advanced: true });
+					this.hooks.audit?.({ event: "gate_advance_recovered", gate_id: latest.gate.gate_id });
+					recovered.push(latest.gate.gate_id);
+				});
+			} finally {
+				this.recovering.delete(listed.gate.gate_id);
+			}
 		}
 		return recovered;
 	}