omp-conductor 0.18.1 → 0.19.0

package/src/arm-challenge.ts

@@ -1,69 +1,154 @@
 /**
  * Authenticated pending-challenge state for the arming handshake (conductor
- * #415).
+ * #415, transaction reworked by #614, storage hardened by review of #896).
  *
  * `armTicks` (fleet.ts) sends a short-lived `FLEET-…` code to the operator and
- * proves the reply by scanning the orchestrator session transcript. That reply
- * also lands in the orchestrator as an ordinary user turn, where the model once
- * ad-libbed pairing-safety prose because it had no trusted way to recognise it.
+ * waits for the orchestrator to acknowledge it. The acknowledgement is
+ * conductor-owned state: the orchestrator's inbound user-turn adapter
+ * (orchestrator-tick.ts) writes it the moment the real reply arrives as a user
+ * turn — never the model, and never a transcript scan, so the proof no longer
+ * depends on where (or whether) a session file lives.
  *
  * This module is the bridge between the two roles without an import cycle:
  * `fleet.ts` imports `daemon.ts`, `daemon.ts` imports `orchestrator-tick.ts`,
  * so `orchestrator-tick.ts` can never import `fleet.ts`. Both already import
- * `config.ts`, so the pending-challenge record lives next to the other state
- * under `stateDir()` and both sides reach it through *this* leaf module.
+ * `config.ts`, so the state lives next to the other state under `stateDir()`
+ * and both sides reach it through *this* leaf module.
+ *
+ * The handshake keeps no shared mutable state at all — every file is named by
+ * its own key, and every deletion is id-addressed, so two processes can
+ * neither lose each other's updates nor delete each other's proofs:
+ *
+ * - `arm-challenges/<project key>.json` — one pending challenge per project:
+ *   `{ project, id, hash, sentAt, expiresAt }`. Host-owned: only `armTicks`
+ *   writes it (record before the send, settle on consumption/timeout/send
+ *   failure), always through the atomic tmp+rename write the admission ack
+ *   uses. A re-armed project overwrites its own file — pruning only its own
+ *   prior id's acknowledgement; a concurrent arm for a different project
+ *   touches a different file.
+ * - `arm-challenge-acks/<challenge id>.json` — one file per acknowledgement:
+ *   `{ challengeId, acknowledgedAt }`. The adapter's acknowledgement is a
+ *   single-file create/overwrite via rename — it never reads or rewrites
+ *   another transaction's record. Files that outlive their transaction (a
+ *   crash between the adapter's write and the host's settle) are inert by
+ *   construction and removed only by age, never by membership in any
+ *   directory snapshot (see {@link gcAgedAcks}).
  *
  * Only the sha-256 of the code is ever persisted — never the code, whose
  * plaintext appearance in the protected session transcript is already the
- * backend proof and must not leak into a durable report, an issue comment, or a
- * diagnostic line the way a new artifact could. The orchestrator classifies a
- * reply by hashing its tokens against this record, so nothing on the east side
- * of the boundary trusts a `FLEET-` prefix.
+ * backend proof and must not leak into a durable report, an issue comment, or
+ * a diagnostic line the way a new artifact could. The id is a random UUID cut
+ * with the challenge, so acknowledgement records are challenge-specific
+ * without carrying anything guessable. Neither side trusts a `FLEET-` prefix:
+ * a reply is classified by hashing its whitespace-separated tokens against
+ * the pending record, so nothing on the east side of the boundary can arm a
+ * fleet with a lookalike.
  */
 
-import { createHash } from "node:crypto";
-import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { createHash, randomUUID } from "node:crypto";
+import { mkdirSync, readFileSync, readdirSync, renameSync, rmSync, statSync, writeFileSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { stateDir } from "./config.ts";
 
-const ARM_CHALLENGE_FILE = "arm-challenge.json";
+const ARM_CHALLENGES_DIR = "arm-challenges";
+const ARM_ACKS_DIR = "arm-challenge-acks";
 
 interface PendingChallenge {
+  /** The project key this pending belongs to, mirrored for read-back checks. */
+  project: string;
+  /** Random transaction id, cut when this challenge was recorded. */
+  id: string;
   /** sha-256 hex of the challenge code — never the code itself. */
   hash: string;
+  /** Unix ms the challenge was recorded, just before the send. */
+  sentAt: number;
   /** Unix ms after which a matching reply is no longer an active proof. */
   expiresAt: number;
 }
 
-/** Keyed by project name; `""` is the pre-multi-project (un-named) spelling. */
-type PendingChallenges = Record<string, PendingChallenge>;
+interface ArmAcknowledgement {
+  /** The exact challenge id this record satisfies. */
+  challengeId: string;
+  /** Unix ms the inbound adapter acknowledged the reply. */
+  acknowledgedAt: number;
+}
+
+function challengesDir(): string {
+  return join(stateDir(), ARM_CHALLENGES_DIR);
+}
+
+function acksDir(): string {
+  return join(stateDir(), ARM_ACKS_DIR);
+}
 
-function challengesPath(): string {
-  return join(stateDir(), ARM_CHALLENGE_FILE);
+function ackPath(challengeId: string): string {
+  return join(acksDir(), `${challengeId}.json`);
 }
 
 function projectKey(project?: string): string {
   return project ?? "";
 }
 
-function readChallenges(): PendingChallenges {
+/**
+ * Filesystem-safe, injective encoding of a project key. Raw names that need
+ * no escaping are used verbatim; everything else (including the empty key of
+ * an unstamped config) becomes `=` plus hex bytes — `=` never appears in the
+ * raw class, so the two namespaces cannot collide.
+ */
+function encodeProjectKey(key: string): string {
+  if (/^[A-Za-z0-9._-]{1,64}$/.test(key) && key !== "." && key !== "..") return key;
+  return `=${[...Buffer.from(key, "utf8")].map((b) => b.toString(16).padStart(2, "0")).join("")}`;
+}
+
+function pendingPath(key: string): string {
+  return join(challengesDir(), `${encodeProjectKey(key)}.json`);
+}
+
+/**
+ * Atomic durable write, exactly like the admission ack: content lands at a
+ * unique temp path and is renamed into place, so every reader — including the
+ * one-shot inbound adapter racing the host — sees either the old file or the
+ * new one, never a mid-truncate parse.
+ */
+function writeFileAtomic(path: string, content: string): void {
+  mkdirSync(dirname(path), { recursive: true });
+  const tmp = `${path}.${process.pid.toString(36)}.${Date.now().toString(36)}.tmp`;
   try {
-    const parsed: unknown = JSON.parse(readFileSync(challengesPath(), "utf8"));
-    if (parsed !== null && typeof parsed === "object" && !Array.isArray(parsed)) {
-      return parsed as PendingChallenges;
-    }
-  } catch {
-    /* absent or unreadable — no active challenge */
+    // 0600 like the other conductor state an operator never shares; the
+    // records are hashes and random ids, but there is no reason to be less
+    // careful.
+    writeFileSync(tmp, content, { mode: 0o600 });
+    renameSync(tmp, path);
+  } catch (err) {
+    rmSync(tmp, { force: true });
+    throw err;
   }
-  return {};
 }
 
-function writeChallenges(map: PendingChallenges): void {
-  const path = challengesPath();
-  mkdirSync(dirname(path), { recursive: true });
-  // 0600 like the other conductor state an operator never shares; the record is
-  // only a hash, but there is no reason to be less careful with it.
-  writeFileSync(path, `${JSON.stringify(map)}\n`, { mode: 0o600 });
+/**
+ * This project's pending challenge parsed from its own file, with every field
+ * validated. Anything absent, torn, garbage, pre-#614, or naming another
+ * project reads as none — fail closed until the host's next transaction
+ * rewrites the file wholesale.
+ */
+function readPendingFor(key: string): PendingChallenge | undefined {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(readFileSync(pendingPath(key), "utf8"));
+  } catch {
+    return undefined;
+  }
+  if (parsed === null || typeof parsed !== "object") return undefined;
+  const pending = parsed as Partial<PendingChallenge>;
+  if (
+    pending.project !== key ||
+    typeof pending.id !== "string" ||
+    typeof pending.hash !== "string" ||
+    typeof pending.expiresAt !== "number"
+  ) {
+    return undefined;
+  }
+  return pending as PendingChallenge;
 }
 
 /** sha-256 hex of the challenge code — the persisted token, never the code. */
@@ -71,42 +156,150 @@ function challengeHash(code: string): string {
   return createHash("sha256").update(code).digest("hex");
 }
 
-/** Register a new active arming challenge, replacing any prior one for the project. */
-export function recordArmChallenge(project: string | undefined, code: string, expiresAt: number): void {
-  const map = readChallenges();
-  map[projectKey(project)] = { hash: challengeHash(code), expiresAt };
-  writeChallenges(map);
+/**
+ * Acknowledgement files outliving their transaction — a crash between the
+ * adapter's write and the host's settle — are inert by construction: no
+ * waiter ever polls their id again, and ids are UUIDs, so no future
+ * transaction can collide with one. They are therefore not swept by
+ * membership (a directory listing captured before another process records is
+ * stale the moment it is taken, and acting on it deletes on-time proofs),
+ * only by age: a file older than {@link ACK_ORPHAN_GC_AFTER_MS} cannot belong
+ * to a live handshake under any configured window, so its mtime alone decides
+ * removal.
+ */
+const ACK_ORPHAN_GC_AFTER_MS = 24 * 60 * 60 * 1000;
+
+function gcAgedAcks(now: number): void {
+  let names: string[] = [];
+  try {
+    names = readdirSync(acksDir());
+  } catch {
+    return; /* no acknowledgements yet */
+  }
+  for (const name of names) {
+    if (!name.endsWith(".json")) continue;
+    const path = join(acksDir(), name);
+    try {
+      if (statSync(path).mtimeMs >= now - ACK_ORPHAN_GC_AFTER_MS) continue;
+    } catch {
+      continue; /* raced away */
+    }
+    rmSync(path, { force: true });
+  }
 }
 
-/** Drop the active challenge for a project once arming completed or timed out. */
-export function clearArmChallenge(project: string | undefined): void {
-  const map = readChallenges();
+/**
+ * Register a new active arming challenge for the project — overwriting the
+ * project's own pending file — and return the transaction id. Before the
+ * overwrite, the project's PRIOR id is read back and exactly that id's
+ * acknowledgement is pruned: project-local cleanup with no directory
+ * snapshot, so another project's handshake cannot lose its proof here no
+ * matter how the calls interleave.
+ */
+export function recordArmChallenge(
+  project: string | undefined,
+  code: string,
+  sentAt: number,
+  expiresAt: number,
+): string {
   const key = projectKey(project);
-  if (!(key in map)) return;
-  delete map[key];
-  writeChallenges(map);
+  // Read the prior record BEFORE the overwrite shadows it.
+  const prior = readPendingFor(key);
+  const id = randomUUID();
+  const record: PendingChallenge = { project: key, id, hash: challengeHash(code), sentAt, expiresAt };
+  writeFileAtomic(pendingPath(key), `${JSON.stringify(record)}\n`);
+  if (prior !== undefined) rmSync(ackPath(prior.id), { force: true });
+  gcAgedAcks(sentAt);
+  return id;
 }
 
 /**
- * Authenticated classification for the orchestrator's turn adapter: a reply is
- * an active arming proof iff the project has a non-expired pending challenge
- * and one of the reply's whitespace-separated tokens hashes to it. The code is
- * matched by hash — matching `transcriptHasUserCode`'s leniency (the code
- * appears as a token) without ever trusting a `FLEET-` prefix or exposing the
- * code to the model's other reads. An unsolicited lookalike that matches no
- * active challenge, and a reply in the wrong project, both stay inert.
+ * The inbound adapter's acknowledgement (conductor #614): classify the reply
+ * against the project's non-expired pending challenge and, on a match,
+ * atomically write the challenge-id-specific acknowledgement record the host
+ * waits on. Returns whether the reply is an active arming proof, driving the
+ * existing deterministic UX path.
  *
- * Clears nothing: the host (`armTicks`) owns clearance once its transcript
- * proof lands, so the two sides cannot race for the record.
+ * Writes only this challenge's own file — it never reads or rewrites any other
+ * record — so a wrong token, wrong project, expired challenge, or a racing
+ * host settle all fail closed without touching anyone else's handshake, and
+ * two projects acknowledging concurrently cannot clobber each other.
  */
-export function isActiveArmProof(project: string | undefined, replyText: string, now: number): boolean {
-  const pending = readChallenges()[projectKey(project)];
-  if (pending === undefined || now >= pending.expiresAt) return false;
-  const targetHash = pending.hash;
+export function acknowledgeArmReply(project: string | undefined, replyText: string, now: number): boolean {
+  const pending = readPendingFor(projectKey(project));
+  if (pending === undefined) return false;
+  if (now >= pending.expiresAt) return false;
   // Challenge codes contain no whitespace, so tokenising on whitespace never
   // splits one; empty replies simply yield no token.
+  const targetHash = pending.hash;
+  let matched = false;
   for (const token of replyText.trim().split(/\s+/)) {
-    if (token.length > 0 && challengeHash(token) === targetHash) return true;
+    if (token.length > 0 && challengeHash(token) === targetHash) {
+      matched = true;
+      break;
+    }
   }
-  return false;
+  if (!matched) return false;
+  // Keyed by the challenge id, so replays overwrite the one record the single
+  // live waiter consumes; a stale id's file can never be created here.
+  const record: ArmAcknowledgement = { challengeId: pending.id, acknowledgedAt: now };
+  writeFileAtomic(ackPath(pending.id), `${JSON.stringify(record)}\n`);
+  return true;
+}
+
+/** The acknowledgement record for one exact challenge id, or undefined. */
+export function readArmAcknowledgement(challengeId: string): ArmAcknowledgement | undefined {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(readFileSync(ackPath(challengeId), "utf8"));
+  } catch {
+    return undefined; /* absent, torn or garbage — not an acknowledgement */
+  }
+  if (parsed === null || typeof parsed !== "object") return undefined;
+  const ack = parsed as { challengeId?: unknown; acknowledgedAt?: unknown };
+  if (ack.challengeId !== challengeId || typeof ack.acknowledgedAt !== "number") return undefined;
+  return { challengeId, acknowledgedAt: ack.acknowledgedAt };
+}
+
+/**
+ * Settle one arm transaction — consumption, timeout, or send failure: remove
+ * the project's pending file iff it still names this transaction, and drop
+ * its acknowledgement. Deletion is id-addressed only, so another project's
+ * records are untouchable by construction, and a same-project replacement
+ * (different id) survives the stale settle.
+ */
+export function clearArmTransaction(project: string | undefined, challengeId: string): void {
+  const key = projectKey(project);
+  const pending = readPendingFor(key);
+  if (pending !== undefined && pending.id === challengeId) rmSync(pendingPath(key), { force: true });
+  rmSync(ackPath(challengeId), { force: true });
+}
+
+export interface ArmChallengeSighting {
+  /** The pending transaction's id — random, not the challenge code. */
+  id: string;
+  /** Unix ms the challenge was recorded, when the record carries it. */
+  sentAt?: number;
+  /** Unix ms the challenge expires, when the record carries it. */
+  expiresAt?: number;
+  /** Present once the inbound adapter acknowledged this challenge id. */
+  acknowledgedAt?: number;
+}
+
+/**
+ * Doctor's view of the project's open transaction, or undefined when none is
+ * recorded. An expired-but-uncleared record is reported, not hidden: it is
+ * inert (a reply past expiry is refused) but lingers until the project's next
+ * arm replaces it.
+ */
+export function observeArmChallenge(project: string | undefined): ArmChallengeSighting | undefined {
+  const pending = readPendingFor(projectKey(project));
+  if (pending === undefined || typeof pending.id !== "string") return undefined;
+  const ack = readArmAcknowledgement(pending.id);
+  return {
+    id: pending.id,
+    ...(typeof pending.sentAt === "number" ? { sentAt: pending.sentAt } : {}),
+    ...(typeof pending.expiresAt === "number" ? { expiresAt: pending.expiresAt } : {}),
+    ...(ack === undefined ? {} : { acknowledgedAt: ack.acknowledgedAt }),
+  };
 }

package/src/ask.ts

@@ -27,7 +27,7 @@
  * decision — nothing here reopens that clock.
  */
 
-import type { DecisionRecord, InterruptCategory, Store } from "./types.ts";
+import type { DecisionRecord, DecisionState, InterruptCategory, Store } from "./types.ts";
 import { INTERRUPT_CATEGORIES } from "./types.ts";
 
 /** The bounded ask tool this package registers on an orchestrator session. */
@@ -373,6 +373,34 @@ export function askParameterSchema(): Record<string, unknown> {
   };
 }
 
+/**
+ * The questionnaire tool's arguments (#947): the spec it belongs to, plus items
+ * that are each exactly one {@link askParameterSchema}. Composed rather than
+ * restated, so an item can never accept something a single ask refuses.
+ */
+export function questionnaireParameterSchema(): Record<string, unknown> {
+  return {
+    type: "object",
+    properties: {
+      "spec-issue": {
+        type: "number",
+        description:
+          "The issue these questions spec out. The answers become that issue's provenance, so a later reader sees why a slice is shaped the way it is instead of re-litigating it.",
+      },
+      items: {
+        type: "array",
+        minItems: 1,
+        maxItems: MAX_QUESTIONNAIRE_ITEMS,
+        description:
+          "The judgement calls only — anything a repo read can answer is your own work, not an operator question. Delivered as one message, answerable in any order, each item resolving independently.",
+        items: askParameterSchema(),
+      },
+    },
+    required: ["spec-issue", "items"],
+    additionalProperties: false,
+  };
+}
+
 /**
  * The ceiling for one ask, in whole seconds. The model may name one, but the
  * enforcement never depends on it: an ask without a `timeoutSeconds` gets the
@@ -411,6 +439,149 @@ export function askMessageFor(request: AskRequest): string {
   return lines.join("\n");
 }
 
+/** The tool name a spec-out questionnaire arrives on (#947). */
+export const QUESTIONNAIRE_TOOL = "conductor_questionnaire";
+
+/** How many items one delivery may carry. A questionnaire longer than this is
+ *  not a questionnaire, it is an interview the operator will abandon halfway —
+ *  and the ceiling that bounds the whole group is one ask's, not one per item. */
+export const MAX_QUESTIONNAIRE_ITEMS = 6;
+
+/**
+ * One spec-out questionnaire (#947): several questions about ONE issue,
+ * delivered together and answerable in any order.
+ *
+ * It is deliberately N {@link AskRequest}s plus a spec binding rather than a
+ * new question shape. Every per-item semantic a spec-out needs — options, a
+ * recommendation, `auto-proceed` versus `park`, the shape ceiling, the
+ * auto-applied marker — already exists and is already tested here; what did not
+ * exist is asking six of them once. Re-deriving those semantics for a
+ * "questionnaire item" would be the same contract in two places, and the second
+ * copy is the one that drifts.
+ */
+export interface QuestionnaireRequest {
+  /** The issue these questions spec out; their answers are its provenance. */
+  specIssue: number;
+  /** The items, in delivery order. Each is an ordinary bounded ask. */
+  items: AskRequest[];
+}
+
+type QuestionnaireParse =
+  | { ok: true; request: QuestionnaireRequest }
+  | { ok: false; problem: string };
+
+/**
+ * Validate one questionnaire call. Strict exactly like {@link parseAskRequest},
+ * and every item is validated through it — including the shape ceiling, which
+ * refuses the **whole group** rather than truncating or dropping one item. A
+ * partially accepted questionnaire would deliver a question set that does not
+ * match the rows behind it, which is the one failure this whole feature exists
+ * to prevent.
+ */
+export function parseQuestionnaireRequest(raw: unknown): QuestionnaireParse {
+  if (raw === null || typeof raw !== "object" || Array.isArray(raw)) {
+    return { ok: false, problem: `${QUESTIONNAIRE_TOOL} arguments must be an object` };
+  }
+  const record = raw as Record<string, unknown>;
+  const known = new Set(["spec-issue", "items"]);
+  for (const key of Object.keys(record)) {
+    if (!known.has(key)) {
+      return { ok: false, problem: `unknown argument "${key}" — expected spec-issue and items` };
+    }
+  }
+  const specIssue = record["spec-issue"];
+  if (typeof specIssue !== "number" || !Number.isInteger(specIssue) || specIssue <= 0) {
+    return {
+      ok: false,
+      problem: 'spec-issue must be the issue number these questions spec out — a questionnaire whose answers belong to nothing is chat history, not provenance',
+    };
+  }
+  const items = record["items"];
+  if (!Array.isArray(items) || items.length === 0) {
+    return { ok: false, problem: "items must be a non-empty array of questions" };
+  }
+  if (items.length > MAX_QUESTIONNAIRE_ITEMS) {
+    return {
+      ok: false,
+      problem: `${items.length} items — over the ${MAX_QUESTIONNAIRE_ITEMS}-item ceiling. Ask the judgement calls only; anything a repo read answers is not an operator question`,
+    };
+  }
+  const parsed: AskRequest[] = [];
+  for (const [index, item] of items.entries()) {
+    const one = parseAskRequest(item);
+    if (!one.ok) return { ok: false, problem: `item ${index + 1}: ${one.problem}` };
+    const shape = validateQuestionShape(one.request.question);
+    if (!shape.ok) return { ok: false, problem: `item ${index + 1}: ${shape.problem}` };
+    parsed.push(one.request);
+  }
+  return { ok: true, request: { specIssue, items: parsed } };
+}
+
+/**
+ * The questionnaire exactly as it is delivered: **one** message, its items
+ * numbered so an operator can answer them in any order by naming the number.
+ *
+ * One delivery is the point. N deliveries would be N interrupts for one
+ * decision, which is what the serial workaround already did and why nothing was
+ * ever answered as a set.
+ */
+export function questionnaireMessageFor(request: QuestionnaireRequest): string {
+  const lines = [`QUESTION: ${request.items.length} calls to spec out #${request.specIssue} — answer by number, in any order.`];
+  for (const [index, item] of request.items.entries()) {
+    const parts = [`${index + 1}. ${item.question}`];
+    if (item.options !== undefined && item.options.length > 0) {
+      parts.push(
+        `   options: ${item.options
+          .map((option) => (option.description === undefined ? option.label : `${option.label} — ${option.description}`))
+          .join("; ")}`,
+      );
+    }
+    if (item.recommended !== undefined) parts.push(`   rec: ${item.recommended}`);
+    // Silence is a real outcome, so it is stated per item rather than once for
+    // the group: a questionnaire may legitimately mix "proceed on my
+    // recommendation" with "this one waits for you".
+    parts.push(
+      `   on silence: ${
+        item.onTimeout === "auto-proceed" ? `applies ${item.recommended ?? "the recommendation"}` : "stays open"
+      }`,
+    );
+    lines.push(parts.join("\n"));
+  }
+  return lines.join("\n");
+}
+
+/** What the ceiling did to one still-open item. */
+export type QuestionnaireItemTimeout =
+  | { kind: "auto-applied"; id: string; resolution: string }
+  | { kind: "parked"; id: string };
+
+/**
+ * Apply the ceiling to a questionnaire, per item (#947).
+ *
+ * Pure, and per item on purpose. The group is one delivery but N decisions: an
+ * item the operator answered keeps that answer, an `auto-proceed` item resolves
+ * with the existing auto-applied marker so the record never reads as a human
+ * choice, and a `park` item stays open. Resolving the group atomically — all or
+ * nothing — would discard the answers the operator did give, which is the
+ * second silent fake this feature has to avoid.
+ */
+export function resolveQuestionnaireTimeouts(
+  items: readonly { id: string; request: AskRequest; answered: boolean }[],
+): QuestionnaireItemTimeout[] {
+  const outcomes: QuestionnaireItemTimeout[] = [];
+  for (const item of items) {
+    if (item.answered) continue;
+    if (item.request.onTimeout === "auto-proceed" && item.request.recommended !== undefined) {
+      outcomes.push({ kind: "auto-applied", id: item.id, resolution: autoApplyResolution(item.request.recommended) });
+      continue;
+    }
+    // `park` — and the impossible-by-parse `auto-proceed` with no
+    // recommendation, which parks rather than inventing one.
+    outcomes.push({ kind: "parked", id: item.id });
+  }
+  return outcomes;
+}
+
 /**
  * The interactive surface a bounded ask posts through when one is available
  * (#722): the same Bot API `reply_markup` `telegram_ask` posts, whose taps are
@@ -776,3 +947,119 @@ export async function performAsk(request: AskRequest, deps: AskDeps): Promise<As
 
   return { outcome, decisionId: row.id, text: `${delivered}\n${text}` };
 }
+
+/** What one {@link QUESTIONNAIRE_TOOL} call produced, per item and as text. */
+export interface QuestionnaireResult {
+  /** The minted group id — the handle for `omp-conductor decision` on any item. */
+  groupId: string;
+  items: { id: string; question: string; state: DecisionState; resolution?: string }[];
+  text: string;
+}
+
+/**
+ * Ask one bounded spec-out questionnaire (#947).
+ *
+ * The shape mirrors {@link performAsk} deliberately — rows before delivery, one
+ * bounded wait, per-item timeout policy applied at the ceiling — with two
+ * differences that are the whole feature:
+ *
+ * 1. **One delivery.** The items go out as a single numbered message, so a
+ *    questionnaire costs one interrupt rather than N.
+ * 2. **N independent resolutions.** The wait ends when every item is closed or
+ *    the ceiling elapses, and the ceiling then applies each item's own policy.
+ *    An item the operator answered keeps that answer.
+ *
+ * It uses the durable text path rather than posting N interactive keyboards,
+ * because N posts is exactly the thing it exists not to do. That means a prose
+ * reply is not itself a row resolution — the same contract a degraded single ask
+ * already has — so the result text names the ids and the command that resolves
+ * them.
+ */
+export async function performQuestionnaire(
+  request: QuestionnaireRequest,
+  deps: AskDeps,
+): Promise<QuestionnaireResult> {
+  const now = deps.now ?? Date.now;
+  const wait = deps.wait ?? sleep;
+
+  // Every row durable, in one transaction, BEFORE the delivery: an operator must
+  // never be shown a question that no row is waiting on.
+  const rows = deps.store.createDecisionGroup(
+    request.items.map((item) => ({
+      project: deps.project,
+      question: item.question,
+      ...(item.blocks === undefined ? {} : { blocks: item.blocks }),
+      at: now(),
+    })),
+    request.specIssue,
+  );
+  const groupId = rows[0]!.groupId!;
+
+  const category = request.items[0]!.category ?? "decision-needed";
+  const delivery = await deps.deliver(questionnaireMessageFor(request), category);
+
+  const ceilingSeconds = resolveAskCeilingSeconds(
+    // One ceiling for the group, taken from the shortest item that named one:
+    // the whole point is that a questionnaire cannot wait longer than an ask.
+    request.items.reduce<number | undefined>(
+      (shortest, item) =>
+        item.timeoutSeconds === undefined ? shortest : Math.min(shortest ?? item.timeoutSeconds, item.timeoutSeconds),
+      undefined,
+    ),
+    deps.configuredCeilingSeconds,
+    deps.turnBudgetSeconds ?? DEFAULT_ASK_TIMEOUT_SECONDS,
+  );
+  const deadline = now() + ceilingSeconds * 1_000;
+  for (;;) {
+    const live = deps.store.decisionGroup(groupId);
+    if (live.every((row) => row.state !== "open")) break;
+    if (now() >= deadline) break;
+    await wait(ASK_POLL_MS);
+  }
+
+  // The ceiling, per item. `resolveDecision` refuses a second resolution, so an
+  // answer that landed in the same instant as the deadline is never overwritten.
+  const atCeiling = deps.store.decisionGroup(groupId);
+  for (const outcome of resolveQuestionnaireTimeouts(
+    atCeiling.map((row, index) => ({
+      id: row.id,
+      request: request.items[index]!,
+      answered: row.state !== "open",
+    })),
+  )) {
+    if (outcome.kind === "auto-applied") {
+      deps.store.resolveDecision(outcome.id, "answered", outcome.resolution, now());
+    }
+  }
+
+  const final = deps.store.decisionGroup(groupId);
+  const items = final.map((row) => ({
+    id: row.id,
+    question: row.question,
+    state: row.state,
+    ...(row.resolution === undefined ? {} : { resolution: row.resolution }),
+  }));
+  const open = items.filter((item) => item.state === "open");
+  const deliveryLine =
+    delivery.kind === "sent"
+      ? `The questionnaire went to the operator as one ${delivery.category} message.`
+      : `The questionnaire is durably held (notice ${delivery.noticeId ?? "?"}, ${delivery.category}); the ` +
+        "daemon releases it with the next digest or working-hours catch-up.";
+  const perItem = items
+    .map(
+      (item, index) =>
+        `${index + 1}. ${item.state}${item.resolution === undefined ? "" : ` — ${item.resolution}`} (${item.id})`,
+    )
+    .join("\n");
+  const closing =
+    open.length === 0
+      ? "Every item is resolved. Apply the answers to the spec now."
+      : `${open.length} item(s) stayed open as declared: park the work each one blocks, and note them in your ` +
+        "report. A prose reply does NOT resolve these rows — map it yourself with " +
+        "`omp-conductor decision resolve <id> --answer \"…\"`.";
+  return {
+    groupId,
+    items,
+    text: `${deliveryLine} Ceiling ${ceilingSeconds}s; #${request.specIssue}.\n${perItem}\n${closing}`,
+  };
+}