@mnemom/mnemom 0.17.34 → 0.17.36

package/dist/vendor/shared/durable-contract/question.d.ts

@@ -0,0 +1,218 @@
+/**
+ * Durable questions (S1 amendment 61, signed off by Wassim 2026-11-02): a locked seat's question to its
+ * owner is a journaled fact, answerable from any surface the owner authenticates on, and the answer
+ * reaches the seat without anyone looking at its screen.
+ *
+ * The model (ruling 34.06.1.1 kept as it is): a question IS an owner_mutation approval with subject
+ * 'question' (schema.ts SUBJECT_SHAPES.question, subject hash over the session only, so a session
+ * has at most one open question). Asking the same question again (same question_sha: same
+ * tool_use_id and questions) returns it; asking a different one while it is open, handed_off
+ * included, is refused 409 durable_question_busy and stores nothing, so one question's answer can
+ * never be handed to another tool call. Amendment 61 adds what M1 left out:
+ *
+ *  1. The seat. A PreToolUse command hook on AskUserQuestion (cli plugin seat-ask.mjs) sends the
+ *     tool's `questions` over the per-seat socket; the seat proxy relays it to the host daemon,
+ *     which holds the executor key and calls ROUTES.exec_question. The api opens (or returns) the
+ *     question approval, stores the question encrypted (durable_approvals.question_ciphertext) and
+ *     journals approval.requested and question.asked {approval_id, question_sha}.
+ *  2. The owner. ROUTES.own_questions lists the session's questions (decrypted, for the owner);
+ *     ROUTES.own_answer answers one ({approval_id, answers, via}) or dismisses it
+ *     ({approval_id, dismiss: true, via}). The api resolves the approval (attestation via = the
+ *     surface), stores the answer encrypted, and journals approval.resolved, approval.consumed and
+ *     question.answered {approval_id, outcome, via}.
+ *  3. Back to the seat, two paths, never both:
+ *     - live: the hook polls ROUTES.exec_question_poll (through the socket and the daemon) while
+ *       the turn is held; on an answer the hook returns permissionDecision "allow" with
+ *       updatedInput {questions, answers}, so the dialog never draws and the tool result carries
+ *       the owner's answer. The poll that hands the answer over marks it taken.
+ *     - hand-off: when the hook's window ends first it calls ROUTES.exec_question_release and
+ *       denies the tool call with QUESTION_HANDOFF_REASON (end the turn; the answer comes as the
+ *       next message). From then on the answer, when it comes (or at release, when it already
+ *       came and was not taken), is delivered as an amendment 60 inbox message from the owner with
+ *       in_reply_to = approval_id, so the seat resumes on it unattended under §60 (e).
+ *
+ * Nothing here carries question or answer text into the journal: refs are ids, shas and enums.
+ * Both question.* kinds stay api-written (writerOf); no executor appends them.
+ */
+/** An AskUserQuestion call carries 1..this many questions. */
+export declare const QUESTION_MAX_QUESTIONS = 4;
+/** Each question offers this many options, min and max (AskUserQuestion's own bounds). */
+export declare const QUESTION_MIN_OPTIONS = 2;
+export declare const QUESTION_MAX_OPTIONS = 4;
+/** A question's text: 1..this many UTF-8 bytes. */
+export declare const QUESTION_TEXT_MAX_BYTES = 2048;
+/** A header chip: 1..this many UTF-8 bytes. */
+export declare const QUESTION_HEADER_MAX_BYTES = 64;
+/** An option label: 1..this many UTF-8 bytes. */
+export declare const QUESTION_LABEL_MAX_BYTES = 256;
+/** An option description: 0..this many UTF-8 bytes. */
+export declare const QUESTION_DESCRIPTION_MAX_BYTES = 2048;
+/** One answer value (a label, labels joined by ", ", or free text): 1..this many UTF-8 bytes. */
+export declare const QUESTION_ANSWER_MAX_BYTES = 4096;
+/** The whole canonical question body: at most this many UTF-8 bytes (it is stored encrypted). */
+export declare const QUESTION_BODY_MAX_BYTES = 16384;
+/**
+ * A question approval's lifetime. Far longer than OWNER_MUTATION_APPROVAL_TTL_S (a device step is
+ * answered now; a question may be answered hours later); an expired question journals
+ * approval.expired and the seat's hook, if still waiting, hands off.
+ */
+export declare const QUESTION_APPROVAL_TTL_S: number;
+/** own_questions answers at most this many questions, newest first. */
+export declare const QUESTION_LIST_LIMIT = 20;
+/** tool_use_id: Claude Code's id of the AskUserQuestion call (opaque, 1..128 of these). */
+export declare const QUESTION_TOOL_USE_ID_RE: RegExp;
+/** A label ending in this marks the option the seat recommends (the AskUserQuestion convention). */
+export declare const QUESTION_RECOMMENDED_SUFFIX = "(Recommended)";
+/**
+ * The surface an answer came from, recorded as the approval attestation's `via` and in
+ * question.answered. The attestation vocabulary of durable_approval_attestations.via, unchanged:
+ * coding_agent (the CLI), slack, webhook, mcp, device (the web device page).
+ */
+export declare const QUESTION_ANSWER_VIAS: readonly ["coding_agent", "slack", "webhook", "mcp", "device"];
+export type QuestionAnswerVia = (typeof QUESTION_ANSWER_VIAS)[number];
+/** question.answered refs.outcome. */
+export declare const QUESTION_OUTCOMES: readonly ["answered", "dismissed"];
+export type QuestionOutcome = (typeof QUESTION_OUTCOMES)[number];
+/**
+ * A question's state as the seat and the owner see it:
+ *  - open: waiting for the owner;
+ *  - answered: the owner answered (answers present);
+ *  - dismissed: the owner dismissed it (no answers);
+ *  - expired: QUESTION_APPROVAL_TTL_S passed unanswered;
+ *  - handed_off: the seat stopped waiting; the answer (if any) goes to the inbox instead.
+ * answered and handed_off can both hold; the poll reports handed_off once the seat released it.
+ */
+export declare const QUESTION_STATES: readonly ["open", "answered", "dismissed", "expired", "handed_off"];
+export type QuestionState = (typeof QUESTION_STATES)[number];
+/** The kinds amendment 61 gives an emitter (they stay in the frozen NO_M1_EMITTER_KINDS M1 baseline). */
+export declare const A61_EMITTED_KINDS: readonly ["question.asked", "question.answered"];
+/** What the hook tells the model when it stops waiting (the tool call is denied with this reason). */
+export declare const QUESTION_HANDOFF_REASON = "This question is now with your owner. End your turn now without guessing; the owner's answer will arrive as your next message.";
+/** What the hook tells the model when the owner dismissed the question. */
+export declare const QUESTION_DISMISSED_REASON = "Your owner dismissed this question without answering. Decide without it, or ask differently.";
+export interface QuestionOption {
+    readonly label: string;
+    readonly description: string;
+}
+export interface QuestionItem {
+    readonly question: string;
+    readonly header: string;
+    readonly options: readonly QuestionOption[];
+    readonly multiSelect: boolean;
+}
+/** One question item: exactly {question, header, options, multiSelect}, labels unique within it. */
+export declare function questionItemOk(v: unknown): v is QuestionItem;
+/**
+ * The questions array as AskUserQuestion takes it: 1..QUESTION_MAX_QUESTIONS items, question texts
+ * unique (they key the answers), the canonical whole within QUESTION_BODY_MAX_BYTES.
+ */
+export declare function questionsOk(v: unknown): v is readonly QuestionItem[];
+/**
+ * Normalise a hook's AskUserQuestion tool_input.questions into the closed shape: keeps exactly the
+ * four keys, fills a missing description with "" and a missing multiSelect with false. Null when
+ * the result is not questionsOk (the hook then leaves the dialog to the screen).
+ */
+export declare function normalizeQuestions(v: unknown): QuestionItem[] | null;
+/** The index of the option the seat recommends (label ends in QUESTION_RECOMMENDED_SUFFIX), else null. */
+export declare function recommendedOption(q: QuestionItem): number | null;
+/** question_sha: sha256 of canonicalJson({v: 1, session_id, tool_use_id, questions}), lowercase hex. */
+export declare function questionShaPreimage(m: {
+    readonly session_id: string;
+    readonly tool_use_id: string;
+    readonly questions: readonly QuestionItem[];
+}): string;
+export declare function questionSha(m: {
+    readonly session_id: string;
+    readonly tool_use_id: string;
+    readonly questions: readonly QuestionItem[];
+}): Promise<string>;
+/**
+ * The answers map AskUserQuestion's updatedInput takes: exactly one key per question text, each a
+ * 1..QUESTION_ANSWER_MAX_BYTES string (a label, several labels joined by ", ", or free text).
+ */
+export declare function answersOk(answers: unknown, questions: readonly QuestionItem[]): answers is Record<string, string>;
+/** The answers map's shape without the questions (the owner route checks it against the stored ones). */
+export declare function answersShapeOk(answers: unknown): answers is Record<string, string>;
+/**
+ * Resolve one owner choice against a question: a 1-based option number (or several, comma
+ * separated, for a multiSelect question), an option label (case-insensitive, with or without the
+ * recommended suffix), or else free text taken as written. Returns the answer string.
+ */
+export declare function answerFromChoice(q: QuestionItem, choice: string): string;
+/**
+ * The inbox body of a handed-off answer (§61 (3)): the api renders it, the inbox delivery line
+ * (inboxDeliveryText) names the approval, so the body only restates question and answer.
+ */
+export declare function questionAnswerInboxBody(questions: readonly QuestionItem[], answers: Readonly<Record<string, string>>): string;
+/** POST exec_question body: exactly {epoch, nonce, tool_use_id, questions}. */
+export declare const QUESTION_ASK_BODY_KEYS: readonly ["epoch", "nonce", "tool_use_id", "questions"];
+export declare function questionAskBodyOk(v: unknown): boolean;
+/**
+ * POST exec_question answer: exactly {approval_id, question_sha, created, expires_at}. created
+ * false: the session's open question was returned, which the api does only when its question_sha
+ * equals this ask's (a different open question is 409 durable_question_busy). The seat checks it
+ * anyway (questionAskMatches) before it polls.
+ */
+export declare function questionAskResponseOk(v: unknown): boolean;
+/**
+ * The seat's own check of an exec_question answer: it is about THIS ask (question_sha equal to the
+ * sha of {session_id, tool_use_id, questions}). The seat polls only a matching approval; otherwise
+ * it denies the tool call without claiming the owner has the question.
+ */
+export declare function questionAskMatches(answer: {
+    readonly question_sha: string;
+}, ask: {
+    readonly session_id: string;
+    readonly tool_use_id: string;
+    readonly questions: readonly QuestionItem[];
+}): Promise<boolean>;
+/** POST exec_question_poll / exec_question_release body: exactly {epoch, nonce, approval_id}. */
+export declare const QUESTION_POLL_BODY_KEYS: readonly ["epoch", "nonce", "approval_id"];
+export declare function questionPollBodyOk(v: unknown): boolean;
+/**
+ * POST exec_question_poll answer: exactly {approval_id, state, answers}. answers is the answers map
+ * iff state is answered (the poll that returns it marks it taken: the hand-off path never delivers
+ * it again), else null.
+ */
+export declare function questionPollResponseOk(v: unknown): boolean;
+/**
+ * POST exec_question_release answer: exactly {approval_id, state, inbox_id}. state is handed_off,
+ * or the final state the question already reached; inbox_id names the inbox message the answer was
+ * queued as (released after the owner answered and before the seat took it), else null.
+ */
+export declare function questionReleaseResponseOk(v: unknown): boolean;
+/**
+ * One own_questions item, exactly these keys; the owner reads the question text (decrypted by the
+ * api). recommended: per question, the index recommendedOption returns (null when none).
+ */
+export declare const QUESTION_LIST_ITEM: Readonly<{
+    approval_id: "uuid";
+    state: "question_state";
+    questions: "questions";
+    recommended: "(integer|null)[]";
+    answers: "answers|null";
+    answered_via: "question_answer_via|null";
+    created_at: "timestamp";
+    expires_at: "timestamp";
+    answered_at: "timestamp|null";
+}>;
+export declare function questionListItemOk(v: unknown): boolean;
+/** GET own_questions: exactly {questions: [item]}, newest first, at most QUESTION_LIST_LIMIT. */
+export declare function questionListResponseOk(v: unknown): boolean;
+/** POST own_answer body: {approval_id, via} plus exactly one of answers or dismiss: true. */
+export declare const QUESTION_ANSWER_BODY_KEYS: readonly ["approval_id", "via", "answers", "dismiss"];
+export declare function questionAnswerBodyOk(v: unknown): boolean;
+/**
+ * POST own_answer answer: exactly {approval_id, outcome, delivery, inbox_id}. delivery says how the
+ * answer reaches the seat: `live` (the seat's hook is waiting and takes it on its next poll),
+ * `inbox` (handed off: inbox_id names the message), or `none` (dismissed).
+ */
+export declare const QUESTION_DELIVERIES: readonly ["live", "inbox", "none"];
+export declare function questionAnswerResponseOk(v: unknown): boolean;
+/** The journal idempotency keys the api uses for question events. */
+export declare const questionIdempotencyKeys: {
+    readonly asked: (approvalId: string) => string;
+    readonly answered: (approvalId: string) => string;
+};
+/** A uuid as the routes take it (re-exported for the CLI's qid argument). */
+export declare const QUESTION_ID_RE: RegExp;

package/dist/vendor/shared/durable-contract/question.js

@@ -0,0 +1,373 @@
+// GENERATED from shared/durable-contract/src/question.ts by cli/scripts/sync-durable-contract.mjs; do not edit.
+/**
+ * Durable questions (S1 amendment 61, signed off by Wassim 2026-11-02): a locked seat's question to its
+ * owner is a journaled fact, answerable from any surface the owner authenticates on, and the answer
+ * reaches the seat without anyone looking at its screen.
+ *
+ * The model (ruling 34.06.1.1 kept as it is): a question IS an owner_mutation approval with subject
+ * 'question' (schema.ts SUBJECT_SHAPES.question, subject hash over the session only, so a session
+ * has at most one open question). Asking the same question again (same question_sha: same
+ * tool_use_id and questions) returns it; asking a different one while it is open, handed_off
+ * included, is refused 409 durable_question_busy and stores nothing, so one question's answer can
+ * never be handed to another tool call. Amendment 61 adds what M1 left out:
+ *
+ *  1. The seat. A PreToolUse command hook on AskUserQuestion (cli plugin seat-ask.mjs) sends the
+ *     tool's `questions` over the per-seat socket; the seat proxy relays it to the host daemon,
+ *     which holds the executor key and calls ROUTES.exec_question. The api opens (or returns) the
+ *     question approval, stores the question encrypted (durable_approvals.question_ciphertext) and
+ *     journals approval.requested and question.asked {approval_id, question_sha}.
+ *  2. The owner. ROUTES.own_questions lists the session's questions (decrypted, for the owner);
+ *     ROUTES.own_answer answers one ({approval_id, answers, via}) or dismisses it
+ *     ({approval_id, dismiss: true, via}). The api resolves the approval (attestation via = the
+ *     surface), stores the answer encrypted, and journals approval.resolved, approval.consumed and
+ *     question.answered {approval_id, outcome, via}.
+ *  3. Back to the seat, two paths, never both:
+ *     - live: the hook polls ROUTES.exec_question_poll (through the socket and the daemon) while
+ *       the turn is held; on an answer the hook returns permissionDecision "allow" with
+ *       updatedInput {questions, answers}, so the dialog never draws and the tool result carries
+ *       the owner's answer. The poll that hands the answer over marks it taken.
+ *     - hand-off: when the hook's window ends first it calls ROUTES.exec_question_release and
+ *       denies the tool call with QUESTION_HANDOFF_REASON (end the turn; the answer comes as the
+ *       next message). From then on the answer, when it comes (or at release, when it already
+ *       came and was not taken), is delivered as an amendment 60 inbox message from the owner with
+ *       in_reply_to = approval_id, so the seat resumes on it unattended under §60 (e).
+ *
+ * Nothing here carries question or answer text into the journal: refs are ids, shas and enums.
+ * Both question.* kinds stay api-written (writerOf); no executor appends them.
+ */
+import { fieldOk } from "./admission.js";
+import { canonicalJson, HEX64_RE, sha256Hex, utf8, UUID_RE } from "./canonical.js";
+// ---- limits ---------------------------------------------------------------------------------
+/** An AskUserQuestion call carries 1..this many questions. */
+export const QUESTION_MAX_QUESTIONS = 4;
+/** Each question offers this many options, min and max (AskUserQuestion's own bounds). */
+export const QUESTION_MIN_OPTIONS = 2;
+export const QUESTION_MAX_OPTIONS = 4;
+/** A question's text: 1..this many UTF-8 bytes. */
+export const QUESTION_TEXT_MAX_BYTES = 2048;
+/** A header chip: 1..this many UTF-8 bytes. */
+export const QUESTION_HEADER_MAX_BYTES = 64;
+/** An option label: 1..this many UTF-8 bytes. */
+export const QUESTION_LABEL_MAX_BYTES = 256;
+/** An option description: 0..this many UTF-8 bytes. */
+export const QUESTION_DESCRIPTION_MAX_BYTES = 2048;
+/** One answer value (a label, labels joined by ", ", or free text): 1..this many UTF-8 bytes. */
+export const QUESTION_ANSWER_MAX_BYTES = 4096;
+/** The whole canonical question body: at most this many UTF-8 bytes (it is stored encrypted). */
+export const QUESTION_BODY_MAX_BYTES = 16384;
+/**
+ * A question approval's lifetime. Far longer than OWNER_MUTATION_APPROVAL_TTL_S (a device step is
+ * answered now; a question may be answered hours later); an expired question journals
+ * approval.expired and the seat's hook, if still waiting, hands off.
+ */
+export const QUESTION_APPROVAL_TTL_S = 24 * 60 * 60;
+/** own_questions answers at most this many questions, newest first. */
+export const QUESTION_LIST_LIMIT = 20;
+/** tool_use_id: Claude Code's id of the AskUserQuestion call (opaque, 1..128 of these). */
+export const QUESTION_TOOL_USE_ID_RE = /^[A-Za-z0-9_-]{1,128}$/;
+/** A label ending in this marks the option the seat recommends (the AskUserQuestion convention). */
+export const QUESTION_RECOMMENDED_SUFFIX = "(Recommended)";
+// ---- vocabularies ---------------------------------------------------------------------------
+/**
+ * The surface an answer came from, recorded as the approval attestation's `via` and in
+ * question.answered. The attestation vocabulary of durable_approval_attestations.via, unchanged:
+ * coding_agent (the CLI), slack, webhook, mcp, device (the web device page).
+ */
+export const QUESTION_ANSWER_VIAS = ["coding_agent", "slack", "webhook", "mcp", "device"];
+/** question.answered refs.outcome. */
+export const QUESTION_OUTCOMES = ["answered", "dismissed"];
+/**
+ * A question's state as the seat and the owner see it:
+ *  - open: waiting for the owner;
+ *  - answered: the owner answered (answers present);
+ *  - dismissed: the owner dismissed it (no answers);
+ *  - expired: QUESTION_APPROVAL_TTL_S passed unanswered;
+ *  - handed_off: the seat stopped waiting; the answer (if any) goes to the inbox instead.
+ * answered and handed_off can both hold; the poll reports handed_off once the seat released it.
+ */
+export const QUESTION_STATES = ["open", "answered", "dismissed", "expired", "handed_off"];
+/** The kinds amendment 61 gives an emitter (they stay in the frozen NO_M1_EMITTER_KINDS M1 baseline). */
+export const A61_EMITTED_KINDS = ["question.asked", "question.answered"];
+/** What the hook tells the model when it stops waiting (the tool call is denied with this reason). */
+export const QUESTION_HANDOFF_REASON = "This question is now with your owner. End your turn now without guessing; the owner's answer will arrive as your next message.";
+/** What the hook tells the model when the owner dismissed the question. */
+export const QUESTION_DISMISSED_REASON = "Your owner dismissed this question without answering. Decide without it, or ask differently.";
+const isObj = (v) => v !== null && typeof v === "object" && !Array.isArray(v);
+const keysExactly = (o, keys) => Object.keys(o).length === keys.length && keys.every((k) => k in o);
+const keysWithin = (o, required, optional) => required.every((k) => k in o) &&
+    Object.keys(o).every((k) => required.includes(k) || optional.includes(k));
+const text = (v, min, max) => typeof v === "string" &&
+    !v.includes("\u0000") &&
+    utf8(v).length >= min &&
+    utf8(v).length <= max;
+const uuid = (v, nullable = false) => fieldOk({ type: "uuid", nullable }, v);
+const ts = (v, nullable = false) => fieldOk({ type: "timestamp", nullable }, v);
+const int = (v, min = 0) => Number.isSafeInteger(v) && v >= min;
+const nonEmpty = (v) => typeof v === "string" && v.length > 0;
+const oneOf = (v, values) => typeof v === "string" && values.includes(v);
+function optionOk(v) {
+    return (isObj(v) &&
+        keysExactly(v, ["label", "description"]) &&
+        text(v.label, 1, QUESTION_LABEL_MAX_BYTES) &&
+        text(v.description, 0, QUESTION_DESCRIPTION_MAX_BYTES));
+}
+/** One question item: exactly {question, header, options, multiSelect}, labels unique within it. */
+export function questionItemOk(v) {
+    if (!isObj(v) ||
+        !keysExactly(v, ["question", "header", "options", "multiSelect"]) ||
+        !text(v.question, 1, QUESTION_TEXT_MAX_BYTES) ||
+        !text(v.header, 1, QUESTION_HEADER_MAX_BYTES) ||
+        typeof v.multiSelect !== "boolean" ||
+        !Array.isArray(v.options) ||
+        v.options.length < QUESTION_MIN_OPTIONS ||
+        v.options.length > QUESTION_MAX_OPTIONS ||
+        !v.options.every(optionOk))
+        return false;
+    const labels = v.options.map((o) => o.label);
+    return new Set(labels).size === labels.length;
+}
+/**
+ * The questions array as AskUserQuestion takes it: 1..QUESTION_MAX_QUESTIONS items, question texts
+ * unique (they key the answers), the canonical whole within QUESTION_BODY_MAX_BYTES.
+ */
+export function questionsOk(v) {
+    if (!Array.isArray(v) || v.length < 1 || v.length > QUESTION_MAX_QUESTIONS)
+        return false;
+    if (!v.every(questionItemOk))
+        return false;
+    const texts = v.map((q) => q.question);
+    if (new Set(texts).size !== texts.length)
+        return false;
+    return utf8(canonicalJson(v)).length <= QUESTION_BODY_MAX_BYTES;
+}
+/**
+ * Normalise a hook's AskUserQuestion tool_input.questions into the closed shape: keeps exactly the
+ * four keys, fills a missing description with "" and a missing multiSelect with false. Null when
+ * the result is not questionsOk (the hook then leaves the dialog to the screen).
+ */
+export function normalizeQuestions(v) {
+    if (!Array.isArray(v))
+        return null;
+    const out = v.map((q) => {
+        const r = isObj(q) ? q : {};
+        const opts = Array.isArray(r.options) ? r.options : [];
+        return {
+            question: r.question,
+            header: r.header,
+            options: opts.map((o) => {
+                const x = isObj(o) ? o : {};
+                return { label: x.label, description: x.description ?? "" };
+            }),
+            multiSelect: r.multiSelect ?? false,
+        };
+    });
+    return questionsOk(out) ? out : null;
+}
+/** The index of the option the seat recommends (label ends in QUESTION_RECOMMENDED_SUFFIX), else null. */
+export function recommendedOption(q) {
+    const i = q.options.findIndex((o) => o.label.trimEnd().endsWith(QUESTION_RECOMMENDED_SUFFIX));
+    return i < 0 ? null : i;
+}
+/** question_sha: sha256 of canonicalJson({v: 1, session_id, tool_use_id, questions}), lowercase hex. */
+export function questionShaPreimage(m) {
+    return canonicalJson({
+        v: 1,
+        session_id: m.session_id,
+        tool_use_id: m.tool_use_id,
+        questions: m.questions,
+    });
+}
+export async function questionSha(m) {
+    return sha256Hex(questionShaPreimage(m));
+}
+/**
+ * The answers map AskUserQuestion's updatedInput takes: exactly one key per question text, each a
+ * 1..QUESTION_ANSWER_MAX_BYTES string (a label, several labels joined by ", ", or free text).
+ */
+export function answersOk(answers, questions) {
+    return (isObj(answers) &&
+        keysExactly(answers, questions.map((q) => q.question)) &&
+        Object.values(answers).every((a) => text(a, 1, QUESTION_ANSWER_MAX_BYTES)));
+}
+/** The answers map's shape without the questions (the owner route checks it against the stored ones). */
+export function answersShapeOk(answers) {
+    return (isObj(answers) &&
+        Object.keys(answers).length >= 1 &&
+        Object.keys(answers).length <= QUESTION_MAX_QUESTIONS &&
+        Object.keys(answers).every((k) => text(k, 1, QUESTION_TEXT_MAX_BYTES)) &&
+        Object.values(answers).every((a) => text(a, 1, QUESTION_ANSWER_MAX_BYTES)));
+}
+/**
+ * Resolve one owner choice against a question: a 1-based option number (or several, comma
+ * separated, for a multiSelect question), an option label (case-insensitive, with or without the
+ * recommended suffix), or else free text taken as written. Returns the answer string.
+ */
+export function answerFromChoice(q, choice) {
+    const c = choice.trim();
+    const byNumber = (s) => {
+        if (!/^[1-9][0-9]*$/.test(s))
+            return null;
+        const o = q.options[Number(s) - 1];
+        return o ? o.label : null;
+    };
+    const parts = q.multiSelect ? c.split(",").map((p) => p.trim()) : [c];
+    if (parts.length > 0 && parts.every((p) => byNumber(p) !== null))
+        return parts.map((p) => byNumber(p)).join(", ");
+    const norm = (s) => s.trim().replace(QUESTION_RECOMMENDED_SUFFIX, "").trim().toLowerCase();
+    const hit = q.options.find((o) => norm(o.label) === norm(c));
+    return hit ? hit.label : c;
+}
+/**
+ * The inbox body of a handed-off answer (§61 (3)): the api renders it, the inbox delivery line
+ * (inboxDeliveryText) names the approval, so the body only restates question and answer.
+ */
+export function questionAnswerInboxBody(questions, answers) {
+    const lines = ["Your owner answered your question:"];
+    for (const q of questions) {
+        lines.push("", `Q: ${q.question}`, `A: ${answers[q.question] ?? ""}`);
+    }
+    return lines.join("\n");
+}
+// ---- wire shapes ----------------------------------------------------------------------------
+/** POST exec_question body: exactly {epoch, nonce, tool_use_id, questions}. */
+export const QUESTION_ASK_BODY_KEYS = ["epoch", "nonce", "tool_use_id", "questions"];
+export function questionAskBodyOk(v) {
+    return (isObj(v) &&
+        keysExactly(v, QUESTION_ASK_BODY_KEYS) &&
+        int(v.epoch) &&
+        nonEmpty(v.nonce) &&
+        typeof v.tool_use_id === "string" &&
+        QUESTION_TOOL_USE_ID_RE.test(v.tool_use_id) &&
+        questionsOk(v.questions));
+}
+/**
+ * POST exec_question answer: exactly {approval_id, question_sha, created, expires_at}. created
+ * false: the session's open question was returned, which the api does only when its question_sha
+ * equals this ask's (a different open question is 409 durable_question_busy). The seat checks it
+ * anyway (questionAskMatches) before it polls.
+ */
+export function questionAskResponseOk(v) {
+    return (isObj(v) &&
+        keysExactly(v, ["approval_id", "question_sha", "created", "expires_at"]) &&
+        uuid(v.approval_id) &&
+        typeof v.question_sha === "string" &&
+        HEX64_RE.test(v.question_sha) &&
+        typeof v.created === "boolean" &&
+        ts(v.expires_at));
+}
+/**
+ * The seat's own check of an exec_question answer: it is about THIS ask (question_sha equal to the
+ * sha of {session_id, tool_use_id, questions}). The seat polls only a matching approval; otherwise
+ * it denies the tool call without claiming the owner has the question.
+ */
+export async function questionAskMatches(answer, ask) {
+    return answer.question_sha === (await questionSha(ask));
+}
+/** POST exec_question_poll / exec_question_release body: exactly {epoch, nonce, approval_id}. */
+export const QUESTION_POLL_BODY_KEYS = ["epoch", "nonce", "approval_id"];
+export function questionPollBodyOk(v) {
+    return (isObj(v) &&
+        keysExactly(v, QUESTION_POLL_BODY_KEYS) &&
+        int(v.epoch) &&
+        nonEmpty(v.nonce) &&
+        uuid(v.approval_id));
+}
+/**
+ * POST exec_question_poll answer: exactly {approval_id, state, answers}. answers is the answers map
+ * iff state is answered (the poll that returns it marks it taken: the hand-off path never delivers
+ * it again), else null.
+ */
+export function questionPollResponseOk(v) {
+    return (isObj(v) &&
+        keysExactly(v, ["approval_id", "state", "answers"]) &&
+        uuid(v.approval_id) &&
+        oneOf(v.state, QUESTION_STATES) &&
+        (v.state === "answered" ? answersShapeOk(v.answers) : v.answers === null));
+}
+/**
+ * POST exec_question_release answer: exactly {approval_id, state, inbox_id}. state is handed_off,
+ * or the final state the question already reached; inbox_id names the inbox message the answer was
+ * queued as (released after the owner answered and before the seat took it), else null.
+ */
+export function questionReleaseResponseOk(v) {
+    return (isObj(v) &&
+        keysExactly(v, ["approval_id", "state", "inbox_id"]) &&
+        uuid(v.approval_id) &&
+        oneOf(v.state, QUESTION_STATES) &&
+        uuid(v.inbox_id, true));
+}
+/**
+ * One own_questions item, exactly these keys; the owner reads the question text (decrypted by the
+ * api). recommended: per question, the index recommendedOption returns (null when none).
+ */
+export const QUESTION_LIST_ITEM = Object.freeze({
+    approval_id: "uuid",
+    state: "question_state",
+    questions: "questions",
+    recommended: "(integer|null)[]",
+    answers: "answers|null",
+    answered_via: "question_answer_via|null",
+    created_at: "timestamp",
+    expires_at: "timestamp",
+    answered_at: "timestamp|null",
+});
+export function questionListItemOk(v) {
+    if (!isObj(v) || !keysExactly(v, Object.keys(QUESTION_LIST_ITEM)))
+        return false;
+    if (!uuid(v.approval_id) || !oneOf(v.state, QUESTION_STATES) || !questionsOk(v.questions))
+        return false;
+    const qs = v.questions;
+    if (!Array.isArray(v.recommended) ||
+        v.recommended.length !== qs.length ||
+        !v.recommended.every((r, i) => r === recommendedOption(qs[i])))
+        return false;
+    const answered = v.answers !== null;
+    if (answered && !answersOk(v.answers, qs))
+        return false;
+    if (answered !== (v.answered_via !== null))
+        return false;
+    if (answered && !oneOf(v.answered_via, QUESTION_ANSWER_VIAS))
+        return false;
+    return ts(v.created_at) && ts(v.expires_at) && ts(v.answered_at, true);
+}
+/** GET own_questions: exactly {questions: [item]}, newest first, at most QUESTION_LIST_LIMIT. */
+export function questionListResponseOk(v) {
+    return (isObj(v) &&
+        keysExactly(v, ["questions"]) &&
+        Array.isArray(v.questions) &&
+        v.questions.length <= QUESTION_LIST_LIMIT &&
+        v.questions.every(questionListItemOk));
+}
+/** POST own_answer body: {approval_id, via} plus exactly one of answers or dismiss: true. */
+export const QUESTION_ANSWER_BODY_KEYS = ["approval_id", "via", "answers", "dismiss"];
+export function questionAnswerBodyOk(v) {
+    if (!isObj(v) || !keysWithin(v, ["approval_id", "via"], ["answers", "dismiss"]))
+        return false;
+    if (!uuid(v.approval_id) || !oneOf(v.via, QUESTION_ANSWER_VIAS))
+        return false;
+    if ("answers" in v === "dismiss" in v)
+        return false;
+    return "dismiss" in v ? v.dismiss === true : answersShapeOk(v.answers);
+}
+/**
+ * POST own_answer answer: exactly {approval_id, outcome, delivery, inbox_id}. delivery says how the
+ * answer reaches the seat: `live` (the seat's hook is waiting and takes it on its next poll),
+ * `inbox` (handed off: inbox_id names the message), or `none` (dismissed).
+ */
+export const QUESTION_DELIVERIES = ["live", "inbox", "none"];
+export function questionAnswerResponseOk(v) {
+    return (isObj(v) &&
+        keysExactly(v, ["approval_id", "outcome", "delivery", "inbox_id"]) &&
+        uuid(v.approval_id) &&
+        oneOf(v.outcome, QUESTION_OUTCOMES) &&
+        oneOf(v.delivery, QUESTION_DELIVERIES) &&
+        (v.delivery === "inbox" ? uuid(v.inbox_id) : v.inbox_id === null) &&
+        (v.outcome === "dismissed" ? v.delivery === "none" : v.delivery !== "none"));
+}
+/** The journal idempotency keys the api uses for question events. */
+export const questionIdempotencyKeys = {
+    asked: (approvalId) => `question:${approvalId}:asked`,
+    answered: (approvalId) => `question:${approvalId}:answered`,
+};
+/** A uuid as the routes take it (re-exported for the CLI's qid argument). */
+export const QUESTION_ID_RE = UUID_RE;