@gajae-code/coding-agent 0.11.1 → 0.11.3

package/src/modes/jobs-observer.ts

@@ -31,6 +31,8 @@ export interface CronJobView {
 	prompt: string;
 	recurring: boolean;
 	nextFireAt?: number;
+	/** A cron firing whose spawned job is currently running. */
+	firing?: boolean;
 	createdAt: number;
 }
 
@@ -140,6 +142,7 @@ export class JobsObserver {
 				recurring: snapshot.recurring,
 				nextFireAt: snapshot.nextFireAt,
 				createdAt: snapshot.createdAt,
+				firing: snapshot.firing,
 			}))
 			.sort((a, b) => b.createdAt - a.createdAt);
 		const worstState: JobsWorstState = this.#failedUnacknowledged

package/src/modes/prompt-action-autocomplete.ts

@@ -248,6 +248,13 @@ export class PromptActionAutocompleteProvider implements AutocompleteProvider {
 
 		return this.#baseProvider.getSuggestions(lines, cursorLine, cursorCol);
 	}
+	getForceFileSuggestions(
+		lines: string[],
+		cursorLine: number,
+		cursorCol: number,
+	): Promise<{ items: AutocompleteItem[]; prefix: string } | null> {
+		return this.#baseProvider.getForceFileSuggestions(lines, cursorLine, cursorCol);
+	}
 
 	applyCompletion(
 		lines: string[],

package/src/modes/runtime-init.ts

@@ -66,6 +66,10 @@ export async function initializeExtensions(session: AgentSession, options: Initi
 			},
 			getActiveTools: () => session.getActiveToolNames(),
 			getAllTools: () => session.getAllToolNames(),
+			resolveTool: name => {
+				const tool = session.getToolByName(name);
+				return tool ? { safeSummary: tool.safeSummary, safeSummaryFields: tool.safeSummaryFields } : undefined;
+			},
 			setActiveTools: (toolNames: string[]) => session.setActiveToolsByName(toolNames),
 			getCommands: () => getSessionSlashCommands(session),
 			setModel: model => runExtensionSetModel(session, model),
@@ -100,6 +104,10 @@ export async function initializeExtensions(session: AgentSession, options: Initi
 			getQueuedMessages: () => session.getQueuedMessageEntries(),
 			getActiveTools: () => session.getActiveToolNames(),
 			getAllTools: () => session.getAllToolNames(),
+			resolveTool: name => {
+				const tool = session.getToolByName(name);
+				return tool ? { safeSummary: tool.safeSummary, safeSummaryFields: tool.safeSummaryFields } : undefined;
+			},
 			shutdown,
 			getContextUsage: () => session.getContextUsage(),
 			getSystemPrompt: () => session.systemPrompt,

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

@@ -11,19 +11,20 @@
  */
 
 import type { OpenGateInput } from "./workflow-gate-broker";
-import type { JsonSchema, WorkflowGateKind, WorkflowStage } from "./workflow-gate-types";
+import {
+	type AskGateDeepInterviewState,
+	buildAskGateAnswerSchema,
+	buildAskGateStageState as buildCanonicalAskGateStageState,
+	type WorkflowGateKind,
+	type WorkflowStage,
+} from "./workflow-gate-types";
 
-/** "Other (type your own)" sentinel, mirroring the interactive ask tool. */
-export const GATE_OTHER_OPTION = "Other (type your own)";
-
-/** Optional structured deep-interview round metadata supplied by the agent. */
-export interface AskGateDeepInterviewState {
-	round_id?: string;
-	round: number;
-	component: string;
-	dimension: string;
-	ambiguity: number;
-}
+export {
+	type AskGateDeepInterviewState,
+	buildAskGateAnswerSchema,
+	GATE_OTHER_OPTION,
+	validateAskGateStageState,
+} from "./workflow-gate-types";
 
 export interface AskGateWorkflowGateMeta {
 	stage: WorkflowStage;
@@ -95,7 +96,7 @@ function deepInterviewQuestionState(questionText: string): Record<string, unknow
 	const state: Record<string, unknown> = {};
 	if (roundMatch) {
 		const round = Number(roundMatch[1]);
-		if (Number.isFinite(round)) state.round = round;
+		if (Number.isSafeInteger(round) && round >= 0) state.round = round;
 		const mode = roundMatch[2]?.trim();
 		if (mode) {
 			state.mode = mode;
@@ -103,8 +104,9 @@ function deepInterviewQuestionState(questionText: string): Record<string, unknow
 			if (normalized.includes("topology")) state.topology_gate = true;
 			if (/(contrarian|simplifier|ontologist)/u.test(normalized)) state.challenge_mode = normalized;
 		}
-		const ambiguity = roundMatch[3]?.trim();
-		if (ambiguity) state.ambiguity = ambiguity;
+		const rawAmbiguity = roundMatch[3]?.trim();
+		const ambiguity = rawAmbiguity === "" || rawAmbiguity === undefined ? Number.NaN : Number(rawAmbiguity);
+		if (Number.isFinite(ambiguity) && ambiguity >= 0 && ambiguity <= 1) state.ambiguity = ambiguity;
 	}
 	if (/Round\s+0\s+\|\s+Topology confirmation/im.test(questionText)) {
 		state.round = 0;
@@ -114,91 +116,25 @@ function deepInterviewQuestionState(questionText: string): Record<string, unknow
 	return state;
 }
 
-function questionAnswerSchema(question: AskGateQuestion, labels: string[]): JsonSchema {
-	const multi = question.multi ?? false;
-	const selectedItems: JsonSchema = { type: "string", enum: labels };
-	const selectedBase: JsonSchema = { type: "array", items: selectedItems, uniqueItems: true };
-	const selectedOnly: JsonSchema = {
-		...selectedBase,
-		minItems: question.allowEmpty ? 0 : 1,
-		...(multi ? {} : { maxItems: 1 }),
-	};
-	const selectedWithOther: JsonSchema = {
-		...selectedBase,
-		...(multi ? {} : { maxItems: 0 }),
-	};
-	return {
-		type: "object",
-		properties: {
-			selected: selectedBase,
-			other: { type: "boolean", description: "set true to provide a free-text answer in `custom`" },
-			custom: {
-				type: "string",
-				minLength: 1,
-				pattern: "\\S",
-				description: "free-text answer; required when `other` is true",
-			},
-			action: {
-				type: "string",
-				enum: ["answer", "clarify"],
-				description: "set to `clarify` to ask about the choices without answering the round",
-			},
-			question: {
-				type: "string",
-				minLength: 1,
-				pattern: "\\S",
-				description: "clarification question; required when action is `clarify`",
-			},
+/** Build and validate exact producer-compatible `stage_state` metadata for one ask question. */
+export function buildAskGateStageState(question: AskGateQuestion, labels: string[]): Record<string, unknown> {
+	return buildCanonicalAskGateStageState(
+		{
+			id: question.id,
+			multi: question.multi,
+			allowEmpty: question.allowEmpty,
+			navigationLabel: question.navigationLabel,
+			deepInterview: question.deepInterview,
+			fallbackState: deepInterviewQuestionState(question.question),
 		},
-		additionalProperties: false,
-		anyOf: [
-			{
-				type: "object",
-				properties: { selected: selectedOnly, other: { const: false }, action: { const: "answer" } },
-				required: ["selected"],
-				additionalProperties: false,
-			},
-			{
-				type: "object",
-				properties: {
-					selected: selectedWithOther,
-					other: { const: true },
-					custom: { type: "string", minLength: 1, pattern: "\\S" },
-					action: { const: "answer" },
-				},
-				required: ["selected", "other", "custom"],
-				additionalProperties: false,
-			},
-			{
-				type: "object",
-				properties: {
-					action: { const: "clarify" },
-					question: { type: "string", minLength: 1, pattern: "\\S" },
-				},
-				required: ["action", "question"],
-				additionalProperties: false,
-			},
-		],
-	};
-}
-
-/** Build `stage_state` round metadata from the structured param (authoritative when present). */
-function structuredDeepInterviewState(meta: AskGateDeepInterviewState): Record<string, unknown> {
-	const state: Record<string, unknown> = {
-		deep_interview_metadata: true,
-		round: meta.round,
-		component: meta.component,
-		dimension: meta.dimension,
-		ambiguity: meta.ambiguity,
-	};
-	if (meta.round_id !== undefined) state.round_id = meta.round_id;
-	return state;
+		labels,
+	);
 }
 
 /** Build the `workflow_gate` open-input for one ask question. */
 export function questionToGate(question: AskGateQuestion): OpenGateInput {
 	const labels = question.options.map(o => o.label);
-	const schema = questionAnswerSchema(question, labels);
+	const schema = buildAskGateAnswerSchema(question, labels);
 	return {
 		stage: question.workflowGate?.stage ?? "deep-interview",
 		kind: question.workflowGate?.kind ?? "question",
@@ -211,18 +147,7 @@ export function questionToGate(question: AskGateQuestion): OpenGateInput {
 		context: {
 			title: question.question,
 			prompt: question.question,
-			stage_state: {
-				question_id: question.id,
-				multi: question.multi ?? false,
-				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)),
-			},
+			stage_state: buildAskGateStageState(question, labels),
 		},
 	};
 }

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

@@ -28,7 +28,7 @@ import type {
 	WorkflowGateValidationError,
 	WorkflowStage,
 } from "./workflow-gate-types";
-import { RESERVED_WORKFLOW_STAGES } from "./workflow-gate-types";
+import { RESERVED_WORKFLOW_STAGES, WORKFLOW_GATE_V1_STAGES } from "./workflow-gate-types";
 
 export type PersistedSemanticDisposition = "commit" | "resolve_without_commit";
 export type PersistedResolutionOrigin =
@@ -108,6 +108,10 @@ export interface WorkflowGateEmitter {
 	setAckRecoveryParticipant?(participant: AskSelectedAckRecoveryParticipant | null): void;
 	/** Explicit host hook for same-process accepted-but-unadvanced recovery. */
 	recoverAcceptedGates?(): Promise<string[]>;
+	/** Reads a durable completed resolution before any presentation claim. */
+	lookupCompletedResolution?(response: WorkflowGateResponse): WorkflowGateCompletedResolutionLookup;
+	/** Supplies the active runtime turn captured immediately before a gate is opened. */
+	setRuntimeTurnProvider?(provider: (() => string | undefined) | null): void;
 	/** Permanently revoke all in-process continuation authority and reject their waiters. */
 	fence?(): void;
 	/** Temporarily make this emitter unavailable while a session transition is reversible. */
@@ -139,6 +143,7 @@ export class BrokerWorkflowGateEmitter implements WorkflowGateEmitter {
 	readonly #runId: string;
 	readonly #store: GateStore;
 	readonly #emitterHooks: Pick<BrokerHooks, "advance">;
+	#runtimeTurnProvider: (() => string | undefined) | undefined;
 
 	constructor(runId: string, store: GateStore, emitterHooks: Pick<BrokerHooks, "advance"> = {}) {
 		this.#runId = runId;
@@ -158,20 +163,29 @@ export class BrokerWorkflowGateEmitter implements WorkflowGateEmitter {
 	isUnattended(): boolean {
 		return true;
 	}
+	setRuntimeTurnProvider(provider: (() => string | undefined) | null): void {
+		this.#runtimeTurnProvider = provider ?? undefined;
+	}
 
 	emitGate(input: OpenGateInput): Promise<unknown> {
 		if (this.#fenced || this.#suspended) return Promise.reject(new Error("workflow gate emitter is unavailable"));
 		const waiter = Promise.withResolvers<unknown>();
-		const gate = this.#broker.openGate(input, {
-			activate: opened => this.#waiters.set(opened.gate_id, waiter),
-			isLive: gateId => this.#waiters.has(gateId),
-			release: gateId => {
-				const activeWaiter = this.#waiters.get(gateId);
-				if (!activeWaiter) return;
-				this.#waiters.delete(gateId);
-				activeWaiter.reject(new Error(`workflow gate ${gateId} continuation was fenced`));
+		const gate = this.#broker.openGate(
+			{
+				...input,
+				...(input.runtimeTurnId === undefined ? { runtimeTurnId: this.#runtimeTurnProvider?.() } : {}),
 			},
-		});
+			{
+				activate: opened => this.#waiters.set(opened.gate_id, waiter),
+				isLive: gateId => this.#waiters.has(gateId),
+				release: gateId => {
+					const activeWaiter = this.#waiters.get(gateId);
+					if (!activeWaiter) return;
+					this.#waiters.delete(gateId);
+					activeWaiter.reject(new Error(`workflow gate ${gateId} continuation was fenced`));
+				},
+			},
+		);
 		// A listener may answer synchronously while the broker emits. The durable
 		// record is the source of truth in that race; never strand its promise.
 		const persisted = this.#store.get(gate.gate_id);
@@ -192,6 +206,10 @@ export class BrokerWorkflowGateEmitter implements WorkflowGateEmitter {
 			throw error;
 		});
 	}
+	lookupCompletedResolution(response: WorkflowGateResponse): WorkflowGateCompletedResolutionLookup {
+		return this.#broker.lookupCompletedResolution(response);
+	}
+
 	prepareTerminalization(gateId: string, proof: WorkflowGateTerminalProof): boolean {
 		return this.#broker.prepareTerminalization(gateId, proof);
 	}
@@ -223,6 +241,7 @@ export class BrokerWorkflowGateEmitter implements WorkflowGateEmitter {
 		if (this.#fenced) return;
 		this.#fenced = true;
 		this.#suspended = false;
+		this.#runtimeTurnProvider = undefined;
 		if (this.#recoveryTimer) clearTimeout(this.#recoveryTimer);
 		this.#recoveryTimer = undefined;
 		if (this.#recoveryGraceTimer) clearTimeout(this.#recoveryGraceTimer);
@@ -467,8 +486,6 @@ export class BrokerWorkflowGateEmitter implements WorkflowGateEmitter {
 	}
 }
 
-const V1_STAGES: readonly WorkflowStage[] = ["deep-interview", "ralplan", "ultragoal"];
-
 export interface PersistedGate {
 	gate: WorkflowGate;
 	status: "pending" | "accepted" | "quarantined";
@@ -760,7 +777,7 @@ function assertFileState(value: unknown, filePath: string): asserts value is Fil
 		invalidFileState(filePath);
 	for (const [stage, counter] of Object.entries(value.counters)) {
 		if (
-			!V1_STAGES.includes(stage as WorkflowStage) ||
+			!WORKFLOW_GATE_V1_STAGES.includes(stage as WorkflowStage) ||
 			typeof counter !== "number" ||
 			!Number.isSafeInteger(counter) ||
 			counter < 0
@@ -805,7 +822,7 @@ function assertPersistedGate(
 	if (
 		gate.type !== "workflow_gate" ||
 		!isNonEmptyString(gate.gate_id) ||
-		!V1_STAGES.includes(stage) ||
+		!WORKFLOW_GATE_V1_STAGES.includes(stage) ||
 		!["question", "approval", "execution"].includes(gate.kind as string) ||
 		!isObject(gate.schema) ||
 		!isNonEmptyString(gate.schema_hash) ||
@@ -814,6 +831,7 @@ function assertPersistedGate(
 		gate.required !== true
 	)
 		invalidFileState(filePath);
+	if (gate.runtime_turn_id !== undefined && !isNonEmptyString(gate.runtime_turn_id)) invalidFileState(filePath);
 	const id = new RegExp(`^wg_[A-Za-z0-9]+_${gate.stage}_(\\d{6,})$`).exec(gate.gate_id);
 	if (
 		!id ||
@@ -1149,11 +1167,24 @@ export interface OpenGateInput {
 	context?: WorkflowGateContext;
 	/** Optional diagnostic gate replaced by this newly persisted gate. */
 	supersedesGateId?: string;
+	/** Optional immutable runtime turn captured by the emitter before broker persistence. */
+	runtimeTurnId?: string;
 }
 
+/** Durable resolution state used to safely replay direct control after presentation retirement. */
+export type WorkflowGateCompletedResolutionLookup =
+	| { kind: "none" }
+	| { kind: "completed"; resolution: WorkflowGateResolution }
+	| { kind: "accepted_incomplete" };
+
 export class WorkflowGateBrokerError extends Error {
 	constructor(
-		readonly code: "unknown_gate" | "already_resolved" | "idempotency_conflict" | "invalid_workflow_stage",
+		readonly code:
+			| "unknown_gate"
+			| "already_resolved"
+			| "idempotency_conflict"
+			| "invalid_workflow_stage"
+			| "invalid_runtime_turn",
 		message: string,
 	) {
 		super(message);
@@ -1212,6 +1243,27 @@ export class WorkflowGateBroker {
 		this.store.put({ ...record, ackPolicy });
 	}
 
+	lookupCompletedResolution(response: WorkflowGateResponse): WorkflowGateCompletedResolutionLookup {
+		const record = this.store.get(response.gate_id);
+		if (!record) return { kind: "none" };
+		const responseHash = answerHashOf({ gate_id: response.gate_id, answer: response.answer });
+		if (record.status !== "accepted" && record.status !== "quarantined") return { kind: "none" };
+		if (record.responseHash === undefined) return { kind: "none" };
+		const sameBody = record.responseHash === responseHash;
+		const sameKey = record.idempotencyKey === response.idempotency_key;
+		if (response.idempotency_key !== undefined && sameKey && !sameBody)
+			throw new WorkflowGateBrokerError(
+				"idempotency_conflict",
+				`idempotency_conflict: gate ${response.gate_id} resolved with a different body`,
+			);
+		if (response.idempotency_key !== undefined && sameKey && sameBody) {
+			if (record.terminalized === true && record.advanced === true && record.resolution)
+				return { kind: "completed", resolution: record.resolution };
+			return { kind: "accepted_incomplete" };
+		}
+		throw new WorkflowGateBrokerError("already_resolved", `already_resolved: gate ${response.gate_id}`);
+	}
+
 	async #terminalize(record: PersistedGate): Promise<void> {
 		const proof = this.#terminalProofs.get(record.gate.gate_id) ?? (await this.hooks.terminalizeAccepted?.(record));
 		this.#terminalProofs.delete(record.gate.gate_id);
@@ -1350,12 +1402,14 @@ export class WorkflowGateBroker {
 
 	/** Open and emit a gate. The pending record is persisted BEFORE emission. */
 	openGate(input: OpenGateInput, continuation?: GateContinuation): WorkflowGate {
-		if (RESERVED_WORKFLOW_STAGES.includes(input.stage) || !V1_STAGES.includes(input.stage)) {
+		if (RESERVED_WORKFLOW_STAGES.includes(input.stage) || !WORKFLOW_GATE_V1_STAGES.includes(input.stage)) {
 			throw new WorkflowGateBrokerError(
 				"invalid_workflow_stage",
 				`stage "${input.stage}" is not a v1 workflow stage`,
 			);
 		}
+		if (input.runtimeTurnId !== undefined && !isNonEmptyString(input.runtimeTurnId))
+			throw new WorkflowGateBrokerError("invalid_runtime_turn", "runtime turn id must be a nonempty string");
 		// Asserts schema shape (throws WorkflowGateSchemaError on unsupported keywords).
 		compileGateSchema(input.schema);
 		const seq = this.store.nextSeq(input.stage).toString().padStart(6, "0");
@@ -1371,6 +1425,7 @@ export class WorkflowGateBroker {
 			context: input.context ?? {},
 			created_at: new Date().toISOString(),
 			required: true,
+			...(input.runtimeTurnId === undefined ? {} : { runtime_turn_id: input.runtimeTurnId }),
 		};
 		if (!continuation) {
 			this.store.put({

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

@@ -3,11 +3,186 @@
 /** Lifecycle stages that emit machine-addressable SDK workflow gates. */
 export type WorkflowStage = "deep-interview" | "ralplan" | "ultragoal";
 
+/** Lifecycle stages included in the v1 workflow-gate contract. */
+export const WORKFLOW_GATE_V1_STAGES: readonly WorkflowStage[] = ["deep-interview", "ralplan", "ultragoal"];
+
 /** Reserved stage names that are explicitly not part of the v1 contract. */
 export const RESERVED_WORKFLOW_STAGES: readonly string[] = ["team"];
 
 export type WorkflowGateKind = "question" | "approval" | "execution";
 
+/** "Other (type your own)" sentinel, mirroring the interactive ask tool. */
+export const GATE_OTHER_OPTION = "Other (type your own)";
+
+export interface AskGateDeepInterviewState {
+	round_id?: string;
+	round: number;
+	component: string;
+	dimension: string;
+	ambiguity: number;
+}
+
+export interface AskGateStageStateInput {
+	id: string;
+	multi?: boolean;
+	allowEmpty?: boolean;
+	navigationLabel?: "Next" | "Done";
+	deepInterview?: AskGateDeepInterviewState;
+	fallbackState?: Record<string, unknown>;
+}
+
+export interface AskGateSchemaInput {
+	multi?: boolean;
+	allowEmpty?: boolean;
+}
+
+function isBoundedAskGateString(value: unknown): value is string {
+	return typeof value === "string" && value.length > 0 && new TextEncoder().encode(value).byteLength <= 256;
+}
+
+/** Rejects stage state that is not exactly compatible with the generic ask-gate producer. */
+export function validateAskGateStageState(value: unknown): asserts value is Record<string, unknown> {
+	if (typeof value !== "object" || value === null || Array.isArray(value))
+		throw new Error("ask gate stage_state must be an object");
+	const state = value as Record<string, unknown>;
+	const allowed = new Set([
+		"question_id",
+		"multi",
+		"allow_empty",
+		"options",
+		"other_option",
+		"clarification_action",
+		"navigation_label",
+		"deep_interview_metadata",
+		"round",
+		"round_id",
+		"component",
+		"dimension",
+		"mode",
+		"challenge_mode",
+		"ambiguity",
+		"topology_gate",
+	]);
+	if (Object.keys(state).some(key => !allowed.has(key))) throw new Error("ask gate stage_state has an unknown field");
+	if (
+		!isBoundedAskGateString(state.question_id) ||
+		typeof state.multi !== "boolean" ||
+		typeof state.allow_empty !== "boolean" ||
+		!Array.isArray(state.options) ||
+		state.options.some(option => !isBoundedAskGateString(option)) ||
+		state.other_option !== GATE_OTHER_OPTION ||
+		state.clarification_action !== "clarify"
+	)
+		throw new Error("ask gate stage_state has invalid required fields");
+	if (state.navigation_label !== undefined && state.navigation_label !== "Next" && state.navigation_label !== "Done")
+		throw new Error("ask gate stage_state has an invalid navigation label");
+	for (const key of ["round_id", "component", "dimension", "mode", "challenge_mode"])
+		if (state[key] !== undefined && !isBoundedAskGateString(state[key]))
+			throw new Error(`ask gate stage_state has an invalid ${key}`);
+	if (state.deep_interview_metadata !== undefined && typeof state.deep_interview_metadata !== "boolean")
+		throw new Error("ask gate stage_state has invalid deep interview metadata");
+	if (state.round !== undefined && (!Number.isSafeInteger(state.round) || (state.round as number) < 0))
+		throw new Error("ask gate stage_state has an invalid round");
+	if (
+		state.ambiguity !== undefined &&
+		(typeof state.ambiguity !== "number" ||
+			!Number.isFinite(state.ambiguity) ||
+			state.ambiguity < 0 ||
+			state.ambiguity > 1)
+	)
+		throw new Error("ask gate stage_state has an invalid ambiguity");
+	if (state.topology_gate !== undefined && typeof state.topology_gate !== "boolean")
+		throw new Error("ask gate stage_state has an invalid topology flag");
+}
+
+/** Builds the canonical generic ask answer schema. */
+export function buildAskGateAnswerSchema(question: AskGateSchemaInput, labels: string[]): JsonSchema {
+	const multi = question.multi ?? false;
+	const selectedItems: JsonSchema = { type: "string", enum: labels };
+	const selectedBase: JsonSchema = { type: "array", items: selectedItems, uniqueItems: true };
+	const selectedOnly: JsonSchema = {
+		...selectedBase,
+		minItems: question.allowEmpty ? 0 : 1,
+		...(multi ? {} : { maxItems: 1 }),
+	};
+	const selectedWithOther: JsonSchema = { ...selectedBase, ...(multi ? {} : { maxItems: 0 }) };
+	return {
+		type: "object",
+		properties: {
+			selected: selectedBase,
+			other: { type: "boolean", description: "set true to provide a free-text answer in `custom`" },
+			custom: {
+				type: "string",
+				minLength: 1,
+				pattern: "\\S",
+				description: "free-text answer; required when `other` is true",
+			},
+			action: {
+				type: "string",
+				enum: ["answer", "clarify"],
+				description: "set to `clarify` to ask about the choices without answering the round",
+			},
+			question: {
+				type: "string",
+				minLength: 1,
+				pattern: "\\S",
+				description: "clarification question; required when action is `clarify`",
+			},
+		},
+		additionalProperties: false,
+		anyOf: [
+			{
+				type: "object",
+				properties: { selected: selectedOnly, other: { const: false }, action: { const: "answer" } },
+				required: ["selected"],
+				additionalProperties: false,
+			},
+			{
+				type: "object",
+				properties: {
+					selected: selectedWithOther,
+					other: { const: true },
+					custom: { type: "string", minLength: 1, pattern: "\\S" },
+					action: { const: "answer" },
+				},
+				required: ["selected", "other", "custom"],
+				additionalProperties: false,
+			},
+			{
+				type: "object",
+				properties: { action: { const: "clarify" }, question: { type: "string", minLength: 1, pattern: "\\S" } },
+				required: ["action", "question"],
+				additionalProperties: false,
+			},
+		],
+	};
+}
+
+/** Builds and validates exact generic ask stage-state metadata. */
+export function buildAskGateStageState(input: AskGateStageStateInput, labels: string[]): Record<string, unknown> {
+	const state: Record<string, unknown> = {
+		question_id: input.id,
+		multi: input.multi ?? false,
+		options: labels,
+		other_option: GATE_OTHER_OPTION,
+		clarification_action: "clarify",
+		allow_empty: input.allowEmpty === true,
+		...(input.navigationLabel === undefined ? {} : { navigation_label: input.navigationLabel }),
+		...(input.deepInterview
+			? {
+					deep_interview_metadata: true,
+					round: input.deepInterview.round,
+					component: input.deepInterview.component,
+					dimension: input.deepInterview.dimension,
+					ambiguity: input.deepInterview.ambiguity,
+					...(input.deepInterview.round_id === undefined ? {} : { round_id: input.deepInterview.round_id }),
+				}
+			: (input.fallbackState ?? {})),
+	};
+	validateAskGateStageState(state);
+	return state;
+}
+
 /** The documented JSON Schema 2020-12 subset supported by the gate validator. */
 export interface JsonSchema {
 	type?: "string" | "number" | "integer" | "boolean" | "object" | "array" | "null";
@@ -60,6 +235,8 @@ export interface WorkflowGate {
 	context: WorkflowGateContext;
 	created_at: string;
 	required: true;
+	/** Immutable runtime turn correlation captured before durable gate visibility. */
+	runtime_turn_id?: string;
 }
 
 /** Non-actionable durable-gate state retained for restart diagnostics. */