omp-onlyne 0.1.0 → 0.3.0

package/src/messages.ts

@@ -1,13 +1,14 @@
-import { OnlyneError, type DeliveryPlan, type Entry, type Message, type NotifyEvent, type Runtime, type TraceEvent } from "@onlyne/lib";
+import { OnlyneError, type DeliveryPlan, type Entry, type Message, type NotifyEvent, type Runtime, type TraceEvent, type WorkRef } from "@onlyne/lib";
 import type { ExtensionAPI, ExtensionContext } from "@oh-my-pi/pi-coding-agent";
 import { AgentRegistry } from "@oh-my-pi/pi-coding-agent/registry/agent-registry";
 import { refreshMailCards, renderMailMessage, type OnlyneMessageDetails } from "./ui/mail-message.ts";
 import type { InboundDecision, JudgeDecider } from "./decider.ts";
-import type { ContextRegistry } from "./store.ts";
-import type { ContextRecord } from "./types.ts";
+import type { ContextRegistry } from "@onlyne/node-host/store";
+import type { ContextRecord } from "@onlyne/node-host/types";
 import { AWAIT_CONSUMED, pendingAwaitResults } from "./tool.ts";
 import { applyMessageTodo, type TodoPlanner } from "./todo.ts";
 import { getRuntime } from "./runtime.ts";
+import { handshakeFacts } from "./handshake.ts";
 import { bridgeText as t } from "./bridge-text.ts";
 
 export const INBOUND = "onlyne.inbound";
@@ -20,6 +21,8 @@ export interface BridgeDeps {
 	decider: JudgeDecider;
 	contexts: ContextRegistry;
 	nodeId: string;
+	/** Wall clock, so the escalation window can be tested without waiting for it. */
+	now?: () => number;
 }
 /**
  * One inbound entry is judged once per process. A retry replays the recorded decision
@@ -31,8 +34,44 @@ interface InboundAttempt {
 	decision?: InboundDecision;
 	failure?: OnlyneError;
 	landed?: string;
+	/** Maintenance passes this entry has been reported landed without being confirmed. */
+	passes?: number;
+	/** Whether the held delivery has already been forced through as a trigger. */
+	escalated?: boolean;
+	/** Set once the second window passed with no confirmation; the warning is written once. */
+	unconfirmed?: boolean;
+	/** How the delivery was submitted: a trigger starts work, a next-turn fragment waits. */
+	delivery?: { via: "trigger" | "nextTurn"; at: number };
 }
+
+/**
+ * How long a next-turn fragment may stay unread before the host offers it again. A turn takes at
+ * least one provider round trip, so a window measured in maintenance passes fires while the
+ * session is still working and duplicates the delivery (dpdp report, follow_up queue).
+ */
+const NEXT_TURN_ESCALATE_MS = 60_000;
+/** Times an entry may be decided again after its binding went away before it is delivered instead. */
+const MAX_REDECISIONS = 2;
 const inboundAttempts = new Map<string, InboundAttempt>();
+/**
+ * Deliveries attempted per entry, kept outside the attempt record: dropping that record is what
+ * makes the next pass decide again, and it must not reset the budget that bounds the deciding.
+ */
+const deliveryAttempts = new Map<string, number>();
+
+function countedAttempt(key: string): number {
+	const next = (deliveryAttempts.get(key) ?? 0) + 1;
+	deliveryAttempts.set(key, next);
+	return next;
+}
+
+/** The end of the line for an entry nothing can hold: the main session takes it once, visibly. */
+function escalate(deps: BridgeDeps, entry: Entry, key: string, reason: string) {
+	const token = registerPending(entry, deps.main.agent.id, "fragment");
+	deps.pi.sendMessage(payload(entry, INBOUND, token), { triggerTurn: true });
+	deps.pi.logger.info("onlyne.delivery.escalated", { entry: key, reason, attempts: deliveryAttempts.get(key) });
+	return { context: deps.main.agent.id, consumed: false, outcome: "delivered" as const };
+}
 
 function inboundKey(entry: Entry): string {
 	return `${entry.thread_ref.owner}/${entry.thread_ref.id}/${entry.seq}`;
@@ -41,6 +80,7 @@ function inboundKey(entry: Entry): string {
 const TRACE_DEBUG = new Set(["inbound.inject", "inbound.duplicate"]);
 
 export function createRuntimeBridge(deps: BridgeDeps): Runtime {
+	const now = deps.now ?? Date.now;
 	return {
 		/**
 		 * Admission is the last cheap place to refuse a plan this host cannot honor (RFC 0005
@@ -56,8 +96,16 @@ export function createRuntimeBridge(deps: BridgeDeps): Runtime {
 			const fields = { ...event } as Record<string, unknown>;
 			const name = String(fields.event);
 			delete fields.event;
-			const thread = fields.thread as { owner?: unknown; id?: unknown } | undefined;
-			if (thread !== undefined) fields.thread = `${String(thread.owner)}/${String(thread.id)}`;
+			// `reconcile.failed` is the one event that names its thread as a bare id beside the
+			// owner, so formatting it as a reference logged `undefined/undefined` and dropped the
+			// id entirely. Every other event carries a real ThreadRef.
+			if (name === "reconcile.failed") {
+				fields.thread = `${String(fields.owner)}/${String(fields.thread)}`;
+				delete fields.owner;
+			} else {
+				const thread = fields.thread as { owner?: unknown; id?: unknown } | undefined;
+				if (thread !== undefined) fields.thread = `${String(thread.owner)}/${String(thread.id)}`;
+			}
 			if (TRACE_DEBUG.has(name)) deps.pi.logger.debug(`onlyne.${name}`, fields);
 			else deps.pi.logger.info(`onlyne.${name}`, fields);
 		},
@@ -87,23 +135,68 @@ export function createRuntimeBridge(deps: BridgeDeps): Runtime {
 				});
 			}
 			if (attempt.failure !== undefined) {
+				// A lost binding cannot be re-decided into existence: past the budget the entry is
+				// delivered to the main session instead, so the judgement stops burning model calls
+				// and the message stops being invisible.
+				if (attempt.failure.error.code === "context_lost" && countedAttempt(key) > MAX_REDECISIONS) {
+					return escalate(deps, entry, key, "context-lost");
+				}
 				deps.pi.logger.debug("onlyne.delivery.held", { entry: key, reason: "judge-failed", error: attempt.failure.message });
 				throw attempt.failure;
 			}
 			const decision = attempt.decision;
 			if (decision === undefined) throw new OnlyneError("decision_unavailable", t("noDecision"));
-			if (decision.action === "new_subagent") {
-				attempt.landed ??= await startSubagent(deps, entry);
-				// A spawn is a submission, not a read: the child's prompt carries the token and its
-				// first provider request is the proof, so nothing is consumed here.
-				return { context: attempt.landed, consumed: false, outcome: "delivered" as const };
-			}
 			// The body is already where the decision put it; re-sending it would append a
 			// second copy that the cursor can only confirm once.
 			if (attempt.landed !== undefined) {
+			// RFC 0008 §5: a delivery is landed only while the context holding it can still
+			// confirm it. A subagent session that ended leaves the entry unconfirmed forever,
+			// and reporting it delivered on every maintenance pass is a retry storm, not a
+			// delivery. Mark the dead binding lost and let the next pass decide again.
+			const holder = (await deps.contexts.list()).find(record => record.agent_id === attempt.landed);
+			if (holder !== undefined && holder.state !== "idle" && holder.state !== "running") {
+				if (countedAttempt(key) > MAX_REDECISIONS) return escalate(deps, entry, key, "context-lost");
+				await deps.contexts.updateState(holder.alias, "lost").catch(() => undefined);
+				inboundAttempts.delete(key);
+				throw new OnlyneError("context_lost", t("contextLost", { alias: holder.alias }), { context: holder.alias });
+			}
+			// A delivery nobody confirmed has two shapes and one bound. A next-turn fragment waits
+			// for an assembly the session may never reach. A trigger starts its own turn, and that
+			// turn can die before the model reads the payload — a provider response at or above 400
+			// drops the observation it recorded — leaving the entry unconfirmed while every pass
+			// reports it delivered. Both are retried once, after a window long enough to be sure the
+			// session is not simply working, and only while it is idle right now.
+			attempt.passes = (attempt.passes ?? 0) + 1;
+			const delivery = attempt.delivery;
+			const waiting = delivery !== undefined && now() - delivery.at >= NEXT_TURN_ESCALATE_MS;
+			if (attempt.landed === deps.main.agent.id && waiting && delivery !== undefined && deps.main.isIdle()) {
+				if (attempt.escalated !== true) {
+					attempt.escalated = true;
+					// The retry opens its own window; measuring the second one from the first send
+					// would report it as unconfirmed on the very next pass.
+					attempt.delivery = { via: "trigger", at: now() };
+					const token = registerPending(entry, deps.main.agent.id, "fragment");
+					deps.pi.sendMessage(payload(entry, INBOUND, token), { triggerTurn: true });
+					deps.pi.logger.info("onlyne.delivery.escalated", {
+						entry: key, reason: "unconfirmed", via: delivery.via, waited_ms: now() - delivery.at,
+					});
+				} else if (attempt.unconfirmed !== true) {
+					// One warning per entry: the reason is recorded once, and the pass stops shouting.
+					attempt.unconfirmed = true;
+					deps.pi.logger.warn("onlyne.delivery.unconfirmed", {
+						entry: key, via: delivery.via, passes: attempt.passes, waited_ms: now() - delivery.at, context: attempt.landed,
+					});
+				}
+			}
 				deps.pi.logger.debug("onlyne.delivery.held", { entry: key, reason: "already-delivered", context: attempt.landed });
 				return { context: attempt.landed, consumed: false, outcome: "delivered" as const };
 			}
+			if (decision.action === "new_subagent") {
+				attempt.landed = await startSubagent(deps, entry);
+				// A spawn is a submission, not a read: the child's prompt carries the token and its
+				// first provider request is the proof, so nothing is consumed here.
+				return { context: attempt.landed, consumed: false, outcome: "delivered" as const };
+			}
 			if (decision.action === "context") {
 				const alias = decision.context;
 				if (alias === undefined) throw new OnlyneError("decision_unavailable", t("noContextNamed"));
@@ -137,8 +230,15 @@ export function createRuntimeBridge(deps: BridgeDeps): Runtime {
 					payload(entry, INBOUND, token),
 					mode === undefined ? { triggerTurn: true } : { deliverAs: mode === "steer" ? "steer" : "followUp" },
 				);
+				attempt.delivery = { via: "trigger", at: now() };
 			} else {
-				deps.pi.sendMessage(payload(entry, INBOUND, token), { deliverAs: "nextTurn" });
+				// RFC 0008 §7: a fragment enters the next context assembly without starting a turn.
+				// An idle session never reaches that assembly by itself, so the entry would sit in
+				// the queue as `injected: false` forever; idle means there is no turn to wait for.
+				const idle = deps.main.isIdle();
+				deps.pi.sendMessage(payload(entry, INBOUND, token), idle ? { triggerTurn: true } : { deliverAs: "nextTurn" });
+				if (idle) deps.pi.logger.info("onlyne.delivery.escalated", { entry: key, reason: "idle-fragment" });
+				attempt.delivery = { via: idle ? "trigger" : "nextTurn", at: now() };
 			}
 			attempt.landed = deps.main.agent.id;
 			deps.pi.logger.info("onlyne.delivery.sent", {
@@ -149,6 +249,13 @@ export function createRuntimeBridge(deps: BridgeDeps): Runtime {
 		},
 		todo: async (entry, context) => {
 			inboundAttempts.delete(inboundKey(entry));
+			deliveryAttempts.delete(inboundKey(entry));
+			// RFC 0018 §3: a handshake status update is delivered for the record, not as work.
+			// Only an entry that owes a decision takes the todo decision path.
+			if (handshakeFacts(entry.message.meta)?.pending === false) {
+				refreshMailCards();
+				return;
+			}
 			const planner: TodoPlanner = {
 				decideTodo: (incoming, current) => deps.decider.decideTodo(deps.main, incoming, current),
 			};
@@ -172,8 +279,7 @@ const pending = new Map<string, PendingObservation>();
 const toolResults = new Map<string, PendingObservation>();
 const observed = new Map<string, string[]>();
 
-function registerPending(entry: Entry, context: string, kind: PendingObservation["kind"]): string {
-	const token = `onlyne-${crypto.randomUUID()}`;
+function registerPending(entry: Entry, context: string, kind: PendingObservation["kind"], token = `onlyne-${crypto.randomUUID()}`): string {
 	pending.set(token, { entry, context, kind });
 	return token;
 }
@@ -283,7 +389,9 @@ async function startSubagent(deps: BridgeDeps, entry: Entry): Promise<string> {
 	await deps.contexts.bind(record.alias, { agent_id: child, ...(parentId === undefined ? {} : { parent_id: parentId }) });
 	// The token is already in the child's prompt, so it can only be registered once the child's
 	// identity is known; until then there is no provider boundary to observe it at.
-	registerPending(entry, child, "fragment");
+	// It is registered as the token the prompt carries: a fresh one would never appear in any
+	// provider payload, and the delivery could never be confirmed.
+	registerPending(entry, child, "fragment", token);
 	return child;
 }
 async function findContextBySource(contexts: ContextRegistry, entry: Entry): Promise<ContextRecord | undefined> {
@@ -314,6 +422,7 @@ function payload(entry: Entry, customType: string, token: string): MessagePayloa
 				from: entry.authenticated_author, at: entry.at, subject: entry.message.delivery_kind, body: entry.message.msg,
 				...(entry.message.meta?.relation === undefined ? {} : { relation: entry.message.meta.relation }),
 				...(entry.message.meta?.in_reply_to === undefined ? {} : { in_reply_to: entry.message.meta.in_reply_to }),
+				...(entry.message.meta?.work === undefined ? {} : { work: entry.message.meta.work }),
 			},
 		} };
 }
@@ -323,5 +432,14 @@ export function registerMessageRenderers(pi: ExtensionAPI): void {
 function renderEntry(entry: Entry, customType: string): string {
 	const label = customType === SUPPLEMENT ? t("labelSupplement") : t("labelInbound");
 	const relation = entry.message.meta?.relation === undefined ? "" : ` · ${entry.message.meta.relation}`;
-	return `${entry.thread_ref.id}/${entry.seq} · ${label} · ${entry.authenticated_author}${relation}\n${entry.message.msg.split(/\r?\n/).map(line => `  > ${line}`).join("\n")}`;
+	const work = workLabel(entry.message.meta?.work);
+	return `${entry.thread_ref.id}/${entry.seq} · ${label} · ${entry.authenticated_author}${relation}${work}\n${entry.message.msg.split(/\r?\n/).map(line => `  > ${line}`).join("\n")}`;
+}
+
+/** The work unit a sender named, so the receiver sees the dedupe key its answer belongs to. */
+export function workLabel(work: WorkRef | undefined): string {
+	if (work === undefined) return "";
+	const parent = work.parent === undefined || work.parent === null ? "" : ` · parent ${work.parent}`;
+	const attempt = work.attempt === undefined ? "" : ` · attempt ${work.attempt}`;
+	return ` · work ${work.unit}${parent}${attempt}`;
 }

package/src/plan.ts

@@ -0,0 +1,133 @@
+import { OnlyneError, type Action, type Json, type NodeId, type ThreadRef } from "@onlyne/lib";
+import { text } from "./decider-text.ts";
+import { choice, type Answers } from "./questions.ts";
+import { reuseThread, type ReplyReference, type ReferenceDeps } from "./resolve.ts";
+
+export type ResponseMode = "await" | "async" | "none";
+export type ExecutionMode = "existing" | "new";
+
+/** The plan fields the caller already fixed in meta. */
+export interface InheritedModes {
+	response?: ResponseMode;
+	execution?: ExecutionMode;
+}
+
+export interface ResourceFields {
+	owner: NodeId;
+	id: string;
+	operation: string;
+}
+
+function stringField(record: Record<string, Json>, key: string): string | undefined {
+	const value = record[key];
+	return typeof value === "string" && value.length > 0 ? value : undefined;
+}
+
+function recordField(record: Record<string, Json>, key: string): Record<string, Json> | undefined {
+	const value = record[key];
+	return value !== null && typeof value === "object" && !Array.isArray(value) ? (value as Record<string, Json>) : undefined;
+}
+
+/**
+ * A plan field the caller stated is binding and is never asked again; a value outside the two
+ * vocabularies is a caller error, never a reason to ask the judge. Anything the caller left out
+ * is decided by the O-3A question, which is why the omission is returned as `undefined` here
+ * rather than filled with a default (audit §2.5).
+ */
+export function inheritedModes(meta: Record<string, Json> | undefined): InheritedModes {
+	if (meta === undefined) return {};
+	const response = meta.response;
+	const execution = meta.execution;
+	if (response !== undefined && response !== "await" && response !== "async" && response !== "none") {
+		throw new OnlyneError("invalid_request", text("error.meta_mode", { key: "response" }));
+	}
+	if (execution !== undefined && execution !== "existing" && execution !== "new") {
+		throw new OnlyneError("invalid_request", text("error.meta_mode", { key: "execution" }));
+	}
+	return {
+		...(response === undefined ? {} : { response }),
+		...(execution === undefined ? {} : { execution }),
+	};
+}
+
+/** The complete plan: what the caller fixed, plus what the judge answered for the rest. */
+export function resolvedModes(inherited: InheritedModes, answers: Answers): { response: ResponseMode; execution: ExecutionMode } {
+	const response = inherited.response ?? choice(answers, "response");
+	const execution = inherited.execution ?? choice(answers, "execution");
+	if (response !== "none" && response !== "async" && response !== "await") {
+		throw new OnlyneError("decision_unavailable", text("error.response_mode"));
+	}
+	if (execution !== "existing" && execution !== "new") {
+		throw new OnlyneError("decision_unavailable", text("error.execution_mode"));
+	}
+	return { response, execution };
+}
+
+/**
+ * The fields a resource operation needs, or `undefined` when the call does not name a complete
+ * one. A partial `meta.resource` is not a resource action, and it is not a reason to fall back
+ * to communication either: the caller named a resource and must finish naming it.
+ */
+export function resourceFields(meta: Record<string, Json> | undefined): ResourceFields | undefined {
+	if (meta === undefined) return undefined;
+	const resource = recordField(meta, "resource");
+	const owner = resource === undefined ? undefined : stringField(resource, "owner");
+	const id = resource === undefined ? undefined : stringField(resource, "id");
+	const operation = stringField(meta, "operation");
+	return owner === undefined || id === undefined || operation === undefined ? undefined : { owner, id, operation };
+}
+
+/** The resource action both the explicit and the judged branch build. */
+export function resourceAction(meta: Record<string, Json> | undefined): Action {
+	const fields = resourceFields(meta);
+	if (fields === undefined) throw new OnlyneError("invalid_request", text("error.resource_action_fields"));
+	const data = meta === undefined ? undefined : meta.data;
+	const revision = meta === undefined ? undefined : meta.expected_revision;
+	return {
+		kind: "resource",
+		resource: { owner: fields.owner, id: fields.id },
+		operation: fields.operation,
+		...(data === undefined ? {} : { data }),
+		...(typeof revision === "string" ? { expected_revision: revision } : {}),
+	};
+}
+
+/**
+ * The thread a send belongs to when the caller named none.
+ *
+ * A reply lands on the thread that holds its original (the client resolves it), and a plan
+ * that says `new` opens a topic. Otherwise the message continues the conversation this node
+ * already has with its addressee: leaving it unnamed makes the client open a thread per
+ * message, and asking the model for an alias it cannot know is the mistake the design already
+ * recorded. This is a lookup over local records, not a judgement (RFC 0016 §5).
+ */
+export async function continueThread(deps: ReferenceDeps, action: Action): Promise<Action> {
+	if (action.kind !== "send" || action.thread !== undefined) return action;
+	if (action.in_reply_to !== undefined || action.execution === "new") return action;
+	const thread = await reuseThread(deps, action.to);
+	return thread === undefined ? action : { ...action, thread };
+}
+
+/** One send action from its resolved references and judged plan. */
+export function sendAction(parts: {
+	to: NodeId;
+	response: "await" | "async" | "none";
+	execution: "existing" | "new";
+	thread?: ThreadRef;
+	context?: string;
+	reply?: ReplyReference;
+	relation?: "reply" | "followup";
+	mentions?: string[];
+}): Action {
+	return {
+		kind: "send",
+		to: parts.to,
+		...(parts.thread === undefined ? {} : { thread: parts.thread }),
+		...(parts.context === undefined ? {} : { context: parts.context }),
+		...(parts.reply === undefined ? {} : { in_reply_to: parts.reply.ref }),
+		...(parts.relation === undefined ? {} : { relation: parts.relation }),
+		...(parts.mentions === undefined ? {} : { mentions: parts.mentions }),
+		response: parts.response,
+		execution: parts.execution,
+	};
+}

package/src/questions.ts

@@ -0,0 +1,250 @@
+import type { NodeId, ThreadRef } from "@onlyne/lib";
+import { text } from "./decider-text.ts";
+import type { PeerRecord } from "./resolve.ts";
+
+/**
+ * The choice catalogs of the decision nodes. Each builder returns the question the judge
+ * answers, with only the options that can actually execute: an option whose choice is
+ * guaranteed to fail is a question the model cannot answer correctly.
+ */
+export interface ChoiceQuestion {
+	type: "choice";
+	instructions: string;
+	criteria: Record<string, string>;
+}
+
+export type Questions = Record<string, ChoiceQuestion>;
+
+export interface ChoiceAnswer {
+	type?: string;
+	choice?: string;
+}
+
+export type Answers = Record<string, ChoiceAnswer | undefined>;
+
+/** The one answer a choice question carries, or `undefined` when the judge gave none. */
+export function choice(answers: Answers, key: string): string | undefined {
+	const answer = answers[key];
+	if (answer === undefined || answer === null || typeof answer !== "object") return undefined;
+	return typeof answer.choice === "string" ? answer.choice : undefined;
+}
+
+/** Node O-1. `resource` is offered only when meta names a complete resource action. */
+export function intentQuestions(options: { resource: boolean }): Questions {
+	return {
+		intent: {
+			type: "choice",
+			instructions: text("judge.o1.instructions"),
+			criteria: {
+				communicate: text("judge.o1.communicate"),
+				inspect: text("judge.o1.inspect"),
+				manage_thread: text("judge.o1.manage_thread"),
+				manage_domain: text("judge.o1.manage_domain"),
+				...(options.resource ? { operate_resource: text("judge.o1.operate_resource") } : {}),
+			},
+		},
+	};
+}
+
+/** Node O-2A, question 1: the relation a reference carries. */
+export function relationQuestions(): Questions {
+	return {
+		relation: {
+			type: "choice",
+			instructions: text("judge.relation.instructions"),
+			criteria: {
+				reply: text("judge.relation.reply"),
+				followup: text("judge.relation.followup"),
+			},
+		},
+	};
+}
+
+/** Node O-3A: whichever of response and execution the caller left open. */
+export function planQuestions(open: { response: boolean; execution: boolean; reply: boolean }): Questions {
+	return {
+		...(open.response
+			? {
+					response: {
+						type: "choice" as const,
+						instructions: text("judge.response.instructions"),
+						criteria: {
+							none: text("judge.response.none"),
+							async: text("judge.response.async"),
+							await: text("judge.response.await"),
+						},
+					},
+				}
+			: {}),
+		...(open.execution
+			? {
+					execution: {
+						type: "choice" as const,
+						instructions: text("judge.execution.instructions"),
+						criteria: {
+							existing: open.reply
+								? text("judge.execution.existing.reply")
+								: text("judge.execution.existing.new"),
+							new: text("judge.execution.new"),
+						},
+					},
+				}
+			: {}),
+	};
+}
+
+/** Node O-3A-Ctx: which published context of the target continues the work. */
+export function contextQuestions(published: Array<{ alias: string; summary: string; state: string }>): Questions {
+	return {
+		context: {
+			type: "choice",
+			instructions: text("judge.context.instructions"),
+			criteria: {
+				...Object.fromEntries(published.map(context => [
+					context.alias,
+					text("judge.context.published", { summary: context.summary, state: context.state }),
+				])),
+				none: text("judge.context.none"),
+			},
+		},
+	};
+}
+
+/** Node O-2A, question 2: the recipient among the peers this node can name. */
+export function targetQuestions(peers: PeerRecord[]): Questions {
+	return {
+		target: {
+			type: "choice",
+			instructions: text("judge.target.instructions"),
+			criteria: {
+				// The abstain exit: an unnamed recipient must surface as ambiguous_target,
+				// never as a low-confidence random pick among peers.
+				none: text("judge.target.none"),
+				...Object.fromEntries(peers.map(peer => [
+					peer.node_id,
+					text("judge.target.peer", {
+						node: peer.node_id,
+						base_url: peer.base_url,
+						instance: peer.instance_id,
+						last_seen: peer.last_seen,
+					}),
+				])),
+			},
+		},
+	};
+}
+
+/** Node O-3B-Th: which local thread a read or thread operation names. */
+export function threadQuestions(threads: Array<{ ref: ThreadRef; title: string; state: string }>): Questions {
+	return {
+		thread: {
+			type: "choice",
+			instructions: text("judge.thread.instructions"),
+			criteria: Object.fromEntries(threads.map(thread => [
+				thread.ref.id,
+				text("judge.thread.item", {
+					title: thread.title,
+					owner: thread.ref.owner,
+					id: thread.ref.id,
+					state: thread.state,
+				}),
+			])),
+		},
+	};
+}
+
+/** Node O-2A: which unanswered inbound message this call answers, or none. */
+export function originalQuestions(
+	facts: Array<{ key: string; from: NodeId; kind: string; thread: string; seq: string; body: string }>,
+): Questions {
+	const criteria: Record<string, string> = { new_message: text("judge.original.new") };
+	for (const fact of facts) {
+		criteria[fact.key] = text("judge.original.candidate", {
+			from: fact.from, kind: fact.kind, thread: fact.thread, seq: fact.seq, body: fact.body,
+		});
+	}
+	return { original: { type: "choice", instructions: text("judge.original.instructions"), criteria } };
+}
+
+/** Node O-2B: which readable channel the message asks about. */
+export function readScopeQuestions(): Questions {
+	return {
+		read_scope: {
+			type: "choice",
+			instructions: text("judge.read_scope.instructions"),
+			criteria: {
+				peers: text("judge.read_scope.peers"),
+				inbox: text("judge.read_scope.inbox"),
+				messages: text("judge.read_scope.messages"),
+				evidence: text("judge.read_scope.evidence"),
+				resources: text("judge.read_scope.resources"),
+				none: text("judge.read_scope.none"),
+			},
+		},
+	};
+}
+
+/** Node O-2C: the local thread operation. */
+export function threadOpQuestions(): Questions {
+	return {
+		thread_op: {
+			type: "choice",
+			instructions: text("judge.thread_op.instructions"),
+			criteria: {
+				create: text("judge.thread_op.create"),
+				close: text("judge.thread_op.close"),
+				list: text("judge.thread_op.list"),
+				describe: text("judge.thread_op.describe"),
+				member_add: text("judge.thread_op.member_add"),
+				member_remove: text("judge.thread_op.member_remove"),
+			},
+		},
+	};
+}
+
+/** Node O-2D: the domain topology operation. */
+export function domainOpQuestions(): Questions {
+	return {
+		domain_op: {
+			type: "choice",
+			instructions: text("judge.domain_op.instructions"),
+			criteria: {
+				create: text("judge.domain_op.create"),
+				join: text("judge.domain_op.join"),
+				leave: text("judge.domain_op.leave"),
+				list: text("judge.domain_op.list"),
+				describe: text("judge.domain_op.describe"),
+				discover: text("judge.domain_op.discover"),
+			},
+		},
+	};
+}
+
+/** Node I-0: whether this node owes the sender an answer. */
+export function needsAnswerQuestions(): Questions {
+	return {
+		needs_answer: {
+			type: "choice",
+			instructions: text("judge.needs_answer.instructions"),
+			criteria: {
+				yes: text("judge.needs_answer.yes"),
+				no: text("judge.needs_answer.no"),
+			},
+		},
+	};
+}
+
+/** Node I-2: how a main-session delivery enters the agent's work. */
+export function insertionQuestions(options: { fragment: boolean }): Questions {
+	return {
+		insertion_mode: {
+			type: "choice",
+			instructions: text("judge.insertion.instructions"),
+			criteria: {
+				steer: text("judge.insertion.steer"),
+				follow_up: text("judge.insertion.follow_up"),
+				...(options.fragment ? { fragment: text("judge.insertion.fragment") } : {}),
+			},
+		},
+	};
+}