@flowdular/sandbox 0.2.9 → 0.3.1

package/src/server/questions.ts

@@ -0,0 +1,356 @@
+/* The active-questions protocol. A specialist that needs a decision from the
+   operator closes its reply with one fenced block tagged `questions`; this
+   module is the only place that turns that text into data, so a malformed block
+   is a turn warning instead of raw JSON the operator has to read. Nothing here
+   touches the file system or the network: the dashboard imports the same
+   parser, so the transcript and the server never disagree about a block. */
+
+export interface PendingQuestion {
+	readonly id: string;
+	readonly question: string;
+	readonly options: readonly string[];
+	/* One of `options`. Absent when the specialist recommends nothing. */
+	readonly recommended?: string;
+	readonly allowFreeText: boolean;
+}
+
+/* What the session carries between the turn that asked and the answers that
+   start the next one: the questions, who asked them, and where. */
+export interface PendingQuestions {
+	/* The transcript sequence of the agent message the block came from. */
+	readonly sequence: number;
+	readonly role: string;
+	readonly module?: string;
+	readonly askedAt: number;
+	readonly questions: readonly PendingQuestion[];
+}
+
+export const MAX_QUESTIONS = 12;
+export const MAX_OPTIONS = 8;
+export const MAX_QUESTION_LENGTH = 400;
+export const MAX_OPTION_LENGTH = 120;
+export const MAX_ANSWER_LENGTH = 400;
+/* The block is a small decision list, not a document: a larger one is refused
+   before JSON.parse allocates it. */
+export const MAX_BLOCK_LENGTH = 8_000;
+
+const QUESTION_ID = /^Q-[0-9]+$/;
+/* A question, an option and an answer each become one line of the decisions the
+   answered turn reads back. A line break or a control character inside one would
+   let the text that wrote it forge further decision lines, so the value is
+   refused whole rather than repaired. */
+const CONTROL_CHARACTER = /[\u0000-\u001F\u007F]/;
+const FENCE = /^[ \t]*```[ \t]*([A-Za-z0-9_-]*)[ \t]*$/;
+/* Every role closes with a handoff line, so it may follow the block. */
+const HANDOFF_LINE = /^[ \t]*(?:[`*_]*)handoff[ \t]*:/i;
+
+export interface QuestionsBlock {
+	readonly raw: string;
+	/* The reply without the block, which is what the transcript speaks. */
+	readonly remainder: string;
+}
+
+export type QuestionsReading =
+	| { readonly kind: 'none' }
+	| {
+			readonly kind: 'valid';
+			readonly questions: readonly PendingQuestion[];
+			readonly remainder: string;
+	  }
+	| {
+			readonly kind: 'invalid';
+			readonly reason: string;
+			readonly remainder: string;
+	  };
+
+interface FencedBlock {
+	readonly tag: string;
+	readonly open: number;
+	readonly close: number;
+}
+
+/* One pass over the lines, pairing fences in order: an opening fence carries
+   the info string, the next fence closes it. An unterminated fence is not a
+   block, so half-streamed output never parses as one. */
+function fencedBlocks(lines: readonly string[]): readonly FencedBlock[] {
+	const blocks: FencedBlock[] = [];
+	let open = -1;
+	let tag = '';
+	for (let index = 0; index < lines.length; index += 1) {
+		const match = FENCE.exec(lines[index]!);
+		if (!match) continue;
+		if (open < 0) {
+			open = index;
+			tag = match[1] ?? '';
+			continue;
+		}
+		blocks.push({ tag, open, close: index });
+		open = -1;
+		tag = '';
+	}
+	return blocks;
+}
+
+/* The block the protocol recognises: tagged `questions`, the last thing in the
+   reply apart from the mandatory handoff line. A block in the middle of an
+   explanation is prose about the protocol, not an instance of it. */
+export function findQuestionsBlock(
+	text: string,
+): QuestionsBlock | { readonly reason: string } | null {
+	if (!text.includes('```')) return null;
+	const lines = text.split('\n');
+	const tagged = fencedBlocks(lines).filter(
+		(block) => block.tag.toLowerCase() === 'questions',
+	);
+	if (tagged.length === 0) return null;
+	if (tagged.length > 1) {
+		return { reason: 'A reply carries at most one questions block.' };
+	}
+	const block = tagged[0]!;
+	for (let index = block.close + 1; index < lines.length; index += 1) {
+		const line = lines[index]!;
+		if (!line.trim() || HANDOFF_LINE.test(line)) continue;
+		return {
+			reason: 'The questions block must be the last thing in the reply.',
+		};
+	}
+	const before = lines.slice(0, block.open);
+	const after = lines.slice(block.close + 1);
+	return {
+		raw: lines.slice(block.open + 1, block.close).join('\n'),
+		remainder: [...before, ...after].join('\n').trim(),
+	};
+}
+
+function invalid(reason: string): {
+	readonly ok: false;
+	readonly reason: string;
+} {
+	return { ok: false, reason };
+}
+
+export type QuestionsParse =
+	| { readonly ok: true; readonly questions: readonly PendingQuestion[] }
+	| { readonly ok: false; readonly reason: string };
+
+/* Every bound is checked before the value is kept, so a session record can only
+   ever hold a list the answers form and the answers route both accept. */
+export function parseQuestionsBlock(raw: string): QuestionsParse {
+	if (raw.length > MAX_BLOCK_LENGTH) {
+		return invalid(
+			`A questions block is limited to ${MAX_BLOCK_LENGTH} characters.`,
+		);
+	}
+	let value: unknown;
+	try {
+		value = JSON.parse(raw) as unknown;
+	} catch {
+		return invalid('The questions block is not valid JSON.');
+	}
+	if (!value || typeof value !== 'object' || Array.isArray(value)) {
+		return invalid('The questions block must be a JSON object.');
+	}
+	const list = (value as { questions?: unknown }).questions;
+	if (!Array.isArray(list) || list.length === 0) {
+		return invalid('The questions block needs a non-empty questions array.');
+	}
+	if (list.length > MAX_QUESTIONS) {
+		return invalid(
+			`A questions block asks at most ${MAX_QUESTIONS} questions.`,
+		);
+	}
+	const questions: PendingQuestion[] = [];
+	const seen = new Set<string>();
+	for (const entry of list as readonly unknown[]) {
+		if (!entry || typeof entry !== 'object' || Array.isArray(entry)) {
+			return invalid('Every question must be a JSON object.');
+		}
+		const item = entry as Record<string, unknown>;
+		const id = item.id;
+		if (typeof id !== 'string' || !QUESTION_ID.test(id)) {
+			return invalid('Every question id must look like Q-1.');
+		}
+		if (seen.has(id)) return invalid(`Question id ${id} is used twice.`);
+		seen.add(id);
+		const question = item.question;
+		if (
+			typeof question !== 'string' ||
+			question.trim().length === 0 ||
+			question.length > MAX_QUESTION_LENGTH
+		) {
+			return invalid(
+				`${id} must ask a question of 1 to ${MAX_QUESTION_LENGTH} characters.`,
+			);
+		}
+		if (CONTROL_CHARACTER.test(question.trim())) {
+			return invalid(
+				`${id} may not contain a line break or a control character.`,
+			);
+		}
+		const rawOptions = item.options ?? [];
+		if (!Array.isArray(rawOptions) || rawOptions.length > MAX_OPTIONS) {
+			return invalid(`${id} may offer at most ${MAX_OPTIONS} options.`);
+		}
+		const options: string[] = [];
+		for (const option of rawOptions as readonly unknown[]) {
+			if (
+				typeof option !== 'string' ||
+				option.trim().length === 0 ||
+				option.length > MAX_OPTION_LENGTH
+			) {
+				return invalid(
+					`Every option of ${id} must be 1 to ${MAX_OPTION_LENGTH} characters.`,
+				);
+			}
+			if (CONTROL_CHARACTER.test(option.trim())) {
+				return invalid(
+					`No option of ${id} may contain a line break or a control character.`,
+				);
+			}
+			if (options.includes(option.trim())) {
+				return invalid(`${id} repeats the option ${option.trim()}.`);
+			}
+			options.push(option.trim());
+		}
+		const allowFreeText = item.allowFreeText ?? false;
+		if (typeof allowFreeText !== 'boolean') {
+			return invalid(`allowFreeText of ${id} must be true or false.`);
+		}
+		if (options.length === 0 && !allowFreeText) {
+			return invalid(
+				`${id} offers no option and no free text, so it cannot be answered.`,
+			);
+		}
+		const recommended = item.recommended;
+		if (recommended !== undefined && recommended !== null) {
+			if (
+				typeof recommended !== 'string' ||
+				!options.includes(recommended.trim())
+			) {
+				return invalid(
+					`The recommendation of ${id} must be one of its options.`,
+				);
+			}
+		}
+		questions.push({
+			id,
+			question: question.trim(),
+			options,
+			...(typeof recommended === 'string' &&
+			options.includes(recommended.trim())
+				? { recommended: recommended.trim() }
+				: {}),
+			allowFreeText,
+		});
+	}
+	return { ok: true, questions };
+}
+
+/* The whole reading of one agent message: whether it asked, what it asked, and
+   what is left to show as speech. */
+export function readQuestions(text: string): QuestionsReading {
+	const found = findQuestionsBlock(text);
+	if (!found) return { kind: 'none' };
+	if ('reason' in found) {
+		return { kind: 'invalid', reason: found.reason, remainder: text };
+	}
+	const parsed = parseQuestionsBlock(found.raw);
+	if (!parsed.ok) {
+		return {
+			kind: 'invalid',
+			reason: parsed.reason,
+			remainder: found.remainder,
+		};
+	}
+	return {
+		kind: 'valid',
+		questions: parsed.questions,
+		remainder: found.remainder,
+	};
+}
+
+export interface AnswerDecision {
+	readonly id: string;
+	readonly question: string;
+	readonly answer: string;
+}
+
+export type AnswersParse =
+	| { readonly ok: true; readonly decisions: readonly AnswerDecision[] }
+	| { readonly ok: false; readonly reason: string };
+
+/* The answers a request carries, checked against the questions this session
+   actually asked: every pending question is answered exactly once, and an
+   answer that is not free text must be one of the offered options. */
+export function resolveAnswers(
+	pending: PendingQuestions,
+	value: unknown,
+): AnswersParse {
+	if (!Array.isArray(value)) {
+		return invalid('answers must be an array.');
+	}
+	if (value.length !== pending.questions.length) {
+		return invalid(
+			`This session is waiting for ${pending.questions.length} answers.`,
+		);
+	}
+	const byId = new Map(pending.questions.map((entry) => [entry.id, entry]));
+	const decisions: AnswerDecision[] = [];
+	for (const entry of value as readonly unknown[]) {
+		if (!entry || typeof entry !== 'object' || Array.isArray(entry)) {
+			return invalid('Every answer must be a JSON object.');
+		}
+		const item = entry as Record<string, unknown>;
+		const id = item.id;
+		if (typeof id !== 'string' || !byId.has(id)) {
+			return invalid('Every answer must name a pending question.');
+		}
+		const question = byId.get(id)!;
+		byId.delete(id);
+		/* A record written before the parser refused these still has to stay out
+		   of the decisions text. */
+		if (CONTROL_CHARACTER.test(question.question)) {
+			return invalid(
+				`${id} carries a line break or a control character and cannot be answered.`,
+			);
+		}
+		const answer = item.answer;
+		if (
+			typeof answer !== 'string' ||
+			answer.trim().length === 0 ||
+			answer.length > MAX_ANSWER_LENGTH
+		) {
+			return invalid(
+				`The answer to ${id} must be 1 to ${MAX_ANSWER_LENGTH} characters.`,
+			);
+		}
+		const trimmed = answer.trim();
+		if (CONTROL_CHARACTER.test(trimmed)) {
+			return invalid(
+				`The answer to ${id} may not contain a line break or a control character.`,
+			);
+		}
+		if (
+			!question.allowFreeText &&
+			question.options.length > 0 &&
+			!question.options.includes(trimmed)
+		) {
+			return invalid(`The answer to ${id} must be one of its options.`);
+		}
+		decisions.push({ id, question: question.question, answer: trimmed });
+	}
+	return { ok: true, decisions };
+}
+
+/* The request text the answered turn starts from. The specialist reads its own
+   questions back with the decision beside each one, so it never has to guess
+   which answer belongs to which question. */
+export function formatDecisions(decisions: readonly AnswerDecision[]): string {
+	return [
+		'Decisions:',
+		...decisions.map(
+			(decision) =>
+				`- ${decision.id}: ${decision.question} -> ${decision.answer}`,
+		),
+	].join('\n');
+}

package/src/server/reference.ts

@@ -36,6 +36,9 @@ export async function referenceSource(
 const REFERENCE_SOURCES: readonly {
 	readonly from: string;
 	readonly to: string;
+	/* A source whose absence is a defect rather than a shape the workspace may
+	   legitimately have, so a failed copy is reported instead of swallowed. */
+	readonly required?: boolean;
 }[] = [
 	{ from: 'packages/server/src', to: 'reference/packages/server/src' },
 	{
@@ -54,6 +57,14 @@ const REFERENCE_SOURCES: readonly {
 		from: 'packages/contracts/schemas',
 		to: 'reference/packages/contracts/schemas',
 	},
+	{
+		from: 'packages/kernel/src/data-class-registry.ts',
+		to: 'reference/packages/kernel/data-class-registry.ts',
+	},
+	{
+		from: 'packages/storage/src/index.ts',
+		to: 'reference/packages/storage/index.ts',
+	},
 	{ from: 'packages/ui/src/index.ts', to: 'reference/packages/ui/index.ts' },
 	{
 		from: 'packages/ui/src/components',
@@ -89,6 +100,11 @@ const REFERENCE_SOURCES: readonly {
 		to: 'reference/auth-core/auth-service.ts',
 	},
 	{ from: 'AGENTS.md', to: 'reference/AGENTS.md' },
+	{
+		from: '.ai/platform-capabilities.md',
+		to: 'reference/platform-capabilities.md',
+		required: true,
+	},
 	{ from: 'docs/design-system.md', to: 'reference/design-system.md' },
 	{ from: 'docs/agent-contract.md', to: 'reference/agent-contract.md' },
 	{ from: '.ai/skills', to: 'reference/skills' },
@@ -109,10 +125,13 @@ not ejected.
 - packages/server: defineEndpoint, HTTP helpers, and the endpoint identity contract.
 - packages/client: the client contribution contract (createClientContribution, ModuleClientContext), shell slots, and shell state.
 - packages/contracts: module manifest, spec, and blueprint schemas.
+- packages/kernel/data-class-registry.ts: the data class declaration a module owning rows makes through context.dataClasses, with its sweep and export operations.
+- packages/storage/index.ts: the object storage port a module writes files through.
 - packages/ui: every shared primitive and the ui-* class list.
 - example-module: a complete module, from ACL to client view, including src/platform.ts. Follow its shape.
 - adapter-module: the same shape on the @flowdular/sdk/database provider contract, with an async repository, dialect-explicit migrations and a lease-owning runtime. Follow it when the module stores data.
 - auth-core: the public surface of auth.core, including its scopes, the PlatformServerContext composition contract, and its service API.
+- platform-capabilities.md: what a module can be built from and what the platform does not have yet. Read it before a specification promises anything.
 - AGENTS.md and design-system.md: the workspace rules that gates enforce.
 - agent-contract.md: detailed lookup reference, not required reading.
 - skills: read only the Task skill named in your Session instruction. Other files are available for later tasks, not for preloading.
@@ -166,7 +185,14 @@ export async function materializeReference(
 				!relative(from, path)
 					.split('/')
 					.some((segment) => EXCLUDED.has(segment)),
-		}).catch(() => undefined);
+		}).catch((error: unknown) => {
+			if (!source.required) return;
+			console.warn(
+				`Sandbox reference: ${source.from} was not copied into the session workspace (${
+					error instanceof Error ? error.message : String(error)
+				}). A skill that cites it will not find it.`,
+			);
+		});
 	}
 	await materializeSdkReference(workspaceRoot, sessionWorkspace);
 	const skills = await listSkills(workspaceRoot);

package/src/server/routes.ts

@@ -78,6 +78,7 @@ import {
 	specPathOf,
 	type ModuleSpecReview,
 } from './spec.ts';
+import { formatDecisions, resolveAnswers } from './questions.ts';
 import type { BrowserSession, SandboxRuntime } from './runtime.ts';
 import { PlatformClient } from './platform-client.ts';
 import { SandboxSetupError } from './workspace-root.ts';
@@ -131,6 +132,7 @@ const STATUS_BY_CODE: Readonly<Record<string, number>> = {
 	MODULE_ALREADY_IN_SESSION: 409,
 	SPEC_NOT_FOUND: 404,
 	SPEC_NOT_APPROVED: 409,
+	NO_PENDING_QUESTIONS: 409,
 	EJECT_SPEC_MISSING: 409,
 	EJECT_SPEC_NOT_APPROVED: 409,
 	EJECT_SPEC_VERSION_UNCHANGED: 409,
@@ -143,6 +145,9 @@ const STATUS_BY_CODE: Readonly<Record<string, number>> = {
 const MAX_SPEC_TEXT = 200_000;
 const MAX_SPEC_COMMENT = 4_000;
 const MAX_JSON_BODY_BYTES = 256_000;
+/* What an operator may add beside the decisions. The decision list is bounded
+   by the questions protocol, so the two together stay inside a turn message. */
+const MAX_ANSWER_NOTE = 8_000;
 
 export interface SandboxRouteOptions {
 	/* The port the launcher bound. A loopback request must name it in its Host
@@ -626,6 +631,14 @@ function assertNotDelivered(session: SandboxSession): void {
 	}
 }
 
+/* The turn one accepted answer set starts: the decisions the specialist reads
+   back, in the role and the module that asked for them. */
+interface AnsweredTurn {
+	readonly message: string;
+	readonly role: string;
+	readonly module?: string;
+}
+
 /* A turn, or a chain of automatically continued turns, runs to completion on
    the server whatever happens to the browser. Streams subscribe to it and can
    leave at any time; stopping is an explicit action. The finished promise is
@@ -666,6 +679,7 @@ export function createSandboxRoutes(
 		sessionId: string,
 		input: {
 			message: string;
+			skillTask?: string;
 			freshContext?: boolean;
 			role?: string;
 			module?: string;
@@ -701,6 +715,7 @@ export function createSandboxRoutes(
 				});
 				let next: {
 					message: string;
+					skillTask?: string;
 					role?: string;
 					module?: string;
 					driver?: string;
@@ -1546,6 +1561,60 @@ export function createSandboxRoutes(
 		},
 	});
 
+	/* Answering the questions the last turn asked is a turn of its own: the
+	   decisions lead the request text, the operator's own words follow them, and
+	   the specialist that asked takes the turn in the module it asked about. */
+	const answerQuestions = new ServerRoute({
+		path: '/sandbox/api/sessions/:id/answers',
+		methods: ['POST'],
+		handler: async (context) => {
+			try {
+				await authorize(runtime, context, options, { mutation: true });
+				const sessionId = sessionIdParam(context);
+				const value = await body(context.request);
+				const note = optionalText(value, 'message', MAX_ANSWER_NOTE);
+				let answered: AnsweredTurn | null = null;
+				/* Reading the questions, resolving them and clearing them is one
+				   step under the session lock: two submissions arriving together
+				   must not both find the same decisions pending and start a turn
+				   from them. */
+				await updateSession(runtime.workspaceRoot, sessionId, (current) => {
+					assertNotArchived(current);
+					assertNotDelivered(current);
+					const pending = current.pendingQuestions;
+					if (!pending || pending.questions.length === 0) {
+						throw new SandboxSetupError(
+							'NO_PENDING_QUESTIONS',
+							'This session is not waiting for a decision.',
+						);
+					}
+					const resolved = resolveAnswers(pending, value.answers);
+					if (!resolved.ok) {
+						throw new SandboxSetupError('INVALID_INPUT', resolved.reason);
+					}
+					const decisions = formatDecisions(resolved.decisions);
+					answered = {
+						message: note ? `${decisions}\n\n${note}` : decisions,
+						role: pending.role,
+						...(pending.module ? { module: pending.module } : {}),
+					};
+					return { pendingQuestions: null };
+				});
+				const turn: AnsweredTurn = answered!;
+				const channel = startTurn(
+					sessionId,
+					/* The decisions text is the specialist's own words read back, so
+					   only the operator's note may name a skill for this turn. */
+					{ ...turn, skillTask: note ?? '' },
+					actingPlatform(runtime, context),
+				);
+				return streamChannel(channel);
+			} catch (error) {
+				return failure(error);
+			}
+		},
+	});
+
 	/* Follow a turn another browser, or an earlier page load, started. */
 	const followTurn = new ServerRoute({
 		path: '/sandbox/api/sessions/:id/turn/stream',
@@ -2232,6 +2301,7 @@ export function createSandboxRoutes(
 		restoreSandboxCheckpoint,
 		removeSandboxSession,
 		turn,
+		answerQuestions,
 		followTurn,
 		stop,
 		settings,

package/src/server/sessions.ts

@@ -15,6 +15,7 @@ import {
 import { isAbsolute, join, relative, resolve } from 'node:path';
 import type { CodingAgentEvent } from '#coding-agent';
 import { sandboxDirectory } from './config.ts';
+import type { PendingQuestions } from './questions.ts';
 import { materializeModuleGraph, materializeReference } from './reference.ts';
 import { hashSpec } from './spec.ts';
 import { forgetDiffs } from './turns.ts';
@@ -121,6 +122,10 @@ export interface SandboxSession {
 	/* Restore points, oldest first. Bounded; see checkpoints.ts for the cap and
 	   the pruning that never drops the start. */
 	readonly checkpoints: readonly SessionCheckpoint[];
+	/* The decisions the last turn asked the operator for, or null when it asked
+	   for none. Every turn rewrites it, so the form can only ever show what the
+	   newest specialist is still waiting on. */
+	readonly pendingQuestions: PendingQuestions | null;
 	readonly state: SandboxSessionState;
 	readonly createdAt: number;
 	readonly updatedAt: number;
@@ -456,6 +461,7 @@ export async function createSession(
 		checkpoints: [
 			{ sequence: 0, at: now, label: 'the starting point', role: input.role },
 		],
+		pendingQuestions: null,
 		state: 'draft',
 		createdAt: now,
 		updatedAt: now,
@@ -551,6 +557,7 @@ export async function readSession(
 			chainDepth: record.chainDepth ?? 0,
 			attachments: record.attachments ?? [],
 			checkpoints: record.checkpoints ?? [],
+			pendingQuestions: record.pendingQuestions ?? null,
 			ejectedAt: record.ejectedAt ?? null,
 			archivedAt: record.archivedAt ?? null,
 		};

package/src/server/turns.ts

@@ -53,6 +53,7 @@ import {
 	type RoutingContext,
 } from './planning.ts';
 import type { PlatformClient } from './platform-client.ts';
+import { readQuestions } from './questions.ts';
 import { listSkills, writeAgentPointer } from './reference.ts';
 import {
 	appendChatEntry,
@@ -97,6 +98,10 @@ export interface TurnInput {
 	readonly freshContext?: boolean;
 	readonly sessionId: string;
 	readonly message: string;
+	/* The operator's own words, when the request text also carries text a
+	   specialist wrote. Only this is scanned for an explicit $skill, so a
+	   question can never choose the skill of the turn that answers it. */
+	readonly skillTask?: string;
 	readonly role?: string;
 	/* The draft module directory this turn works in. Defaults to the module the
 	   last handoff named, then to the primary module. */
@@ -646,7 +651,14 @@ export async function* runTurn(
 		sessionKind: active.kind === 'new' ? 'new-module' : 'edit-module',
 		blueprint: session.blueprint,
 		task: message,
+		...(input.skillTask === undefined
+			? {}
+			: { explicitSkillSource: input.skillTask }),
 		available: await listSkills(context.workspaceRoot),
+		/* The gate of the module this turn works in, read before the driver ran:
+		   until the operator approved that exact text there is nothing to
+		   implement from, so a new module starts as an interview. */
+		specApproved: gate.approved === true,
 	});
 	const reviewing = skill === 'auto-review';
 	if (reviewing) await prepareAutoReview(context.workspaceRoot, paths, active);
@@ -736,6 +748,9 @@ export async function* runTurn(
 	let nextResumeId = resumeId;
 	let failed = false;
 	let closing = '';
+	/* The transcript entry the closing message landed on, so a questions block
+	   the operator answers stays tied to the message that asked. */
+	let closingSequence = 0;
 	/* This snapshot is the enforcement point for role ownership. The workspace
 	   remains readable to the agent, but changes outside its module allowlist are
 	   quarantined and restored before any formatter, gate, checkpoint or delivery
@@ -758,14 +773,18 @@ export async function* runTurn(
 			model: session.model,
 			signal: input.signal,
 		})) {
-			yield await appendChatEntry(context.workspaceRoot, session, {
+			const recorded = await appendChatEntry(context.workspaceRoot, session, {
 				kind: eventKind(event),
 				role: roleId,
 				module: active.directory,
 				...(event.type === 'assistant.message' ? { text: event.text } : {}),
 				event,
 			});
-			if (event.type === 'assistant.message') closing = event.text;
+			yield recorded;
+			if (event.type === 'assistant.message') {
+				closing = event.text;
+				closingSequence = recorded.sequence;
+			}
 			if (event.type === 'turn.completed') {
 				nextResumeId = event.resumeId ?? nextResumeId;
 				failed = event.finishReason === 'error';
@@ -809,6 +828,19 @@ export async function* runTurn(
 		});
 	}
 
+	/* A specialist that needs decisions closes with a questions block. A block
+	   the protocol cannot read is a warning on this turn, never a failure: the
+	   words of the reply still stand. */
+	const asked = closing ? readQuestions(closing) : ({ kind: 'none' } as const);
+	if (asked.kind === 'invalid') {
+		yield await appendChatEntry(context.workspaceRoot, session, {
+			kind: 'system',
+			role: roleId,
+			module: active.directory,
+			text: `The questions block in this reply was ignored: ${asked.reason}`,
+		});
+	}
+
 	const scaffoldNote =
 		failed || reviewing ? null : await scaffoldFromSpec(context, session);
 	if (scaffoldNote) {
@@ -1013,6 +1045,16 @@ export async function* runTurn(
 	if (nextResumeId) resumeIds[resumeKey] = nextResumeId;
 	const updated = await updateSession(context.workspaceRoot, session.id, {
 		resumeIds,
+		pendingQuestions:
+			asked.kind === 'valid' && !failed
+				? {
+						sequence: closingSequence,
+						role: roleId,
+						module: active.directory,
+						askedAt: Date.now(),
+						questions: asked.questions,
+					}
+				: null,
 		state: failed
 			? 'failed'
 			: handoff.kind === 'approval' || handoff.kind === 'question'