in2-agent-server 0.20260821.185429

package/dist/tools/feedback.js

@@ -0,0 +1,318 @@
+import { z } from "zod";
+import { fail, internalError, ok } from "../core/result.js";
+import { TELEMETRY_STAGES } from "../core/telemetry.js";
+import { FEEDBACK_BOUNDS, FEEDBACK_COUNTS, FEEDBACK_LIMITS, betaEnabled, newFeedbackId, recordFeedback } from "../core/betaFeedback.js";
+// THE BETA FEEDBACK TOOLS — registered ONLY when `CC_MCP_BETA` is on.
+//
+// Two tools, two voices: the model reporting where it got tripped up, and the operator's own words
+// about how the batch went. See core/betaFeedback.ts for the channel, and
+// docs/plans/2026-08-03-005-beta-feedback-channel.md for why each argument is the shape it is.
+//
+// NEITHER TOOL ACCEPTS IDENTITY. There is no batchId, sessionId, installId or serverVersion
+// argument on either one, and that is not an omission to be helpfully corrected later: the server
+// attaches all of it from the batch grant, so a report can only ever be attributed to the batch
+// whose credential ships it. Every other content route in this system holds the same line.
+/**
+ * THE FROZEN OPERATOR QUESTIONS.
+ *
+ * Longitudinal comparability depends on never editing these. Two rating questions and one open one,
+ * asked in this order, on every batch while in beta: CES first because effort is the headline metric
+ * (the product's pitch is less friction than the manual process, so the effort trend IS the pitch,
+ * measured), CSAT second because outcome quality is a separate thing — a batch can deliver perfectly
+ * and still have been painful, and the split is what makes that visible.
+ *
+ * `frozenQuestions.test.ts` pins every string here verbatim, so editing one breaks a named test
+ * rather than silently splitting the trend line in two.
+ */
+export const OPERATOR_QUESTIONS = {
+    ease: "How easy was it to get this batch delivered?",
+    satisfaction: "How satisfied are you with what was delivered?",
+    open: "What almost stopped you, or what would you change?",
+    manualEstimate: "If you were implementing these N requirements by hand, how long would it take you?",
+    pmf: "How would you feel if you could no longer use IN2?"
+};
+/**
+ * THE FROZEN OPTION LABELS — four per card, and the number four is not an aesthetic choice.
+ *
+ * An AskUserQuestion card holds AT MOST FOUR OPTIONS, and every operator question in this channel is
+ * delivered as a card. So the rating scales are 4-point forced-choice — no neutral midpoint, stored
+ * 1-4 — rather than the 1-5 first drafted against a chat-typed answer. Forced choice is a real
+ * property and not a consolation: with four points the operator must lean, and a beta cohort small
+ * enough to count individually produces no useful signal from a pile of 3-out-of-5s.
+ *
+ * THE NUMBER TRAVELS IN THE LABEL (`Very easy (4)`) so the stored integer and the words the operator
+ * tapped can never be reconstructed apart. A label of "Very easy" alone would leave the direction of
+ * the scale living only in a describe() string that no stored row carries.
+ *
+ * Highest first, in both scales, because a card reads top-down and the two must not disagree with
+ * each other about which end is good.
+ */
+export const OPERATOR_OPTIONS = {
+    ease: ["Very easy (4)", "Easy (3)", "Difficult (2)", "Very difficult (1)"],
+    satisfaction: ["Very satisfied (4)", "Satisfied (3)", "Dissatisfied (2)", "Very dissatisfied (1)"],
+    /**
+     * Added 2026-08-07 — the only question here that had none, which is why it could gain some.
+     *
+     * QA round 2: *"what almost stopped you or what would you change, that one felt weird not being a
+     * multiple choice kind of thing."* He was right about the asymmetry: every other card in this
+     * channel is answered by TAPPING, and this one alone demanded typing at the end of a long run —
+     * the moment with the least appetite for composition.
+     *
+     * ADDING OPTIONS FORKS NO BUCKET. The freeze protects against a RE-WORDED label splitting a series
+     * that rows already carry; `open` has no stored labels to split, and its question string is
+     * unchanged. So this is the one edit in the four QA raised that costs nothing in comparability.
+     *
+     * THEY ARE A PROMPT, NOT A REPLACEMENT. A tap says which bucket and never why, and the why is what
+     * a beta reads this question for — so "Other" remains the verbatim path and `openAnswer` still
+     * stores their words. The four are the failure modes QA itself surfaced (fatigue, duration,
+     * opacity about what changed) plus the honest "nothing", which has to be tappable or a clean run
+     * gets pushed into inventing a complaint — the operator-side twin of `ranCleanly`.
+     */
+    open: [
+        "Nothing — it went smoothly",
+        "Too many questions to answer",
+        "It took longer than I expected",
+        "I couldn't tell what it had actually changed"
+    ],
+    /** §9.1 — buckets, not a free number, because a bucket is one tap and a number is a negotiation. */
+    manualEstimate: ["Under 30 minutes", "30–60 minutes", "1–3 hours", "More than 3 hours"],
+    /** §9.2 — the canonical Sean Ellis wording. Categorical, exactly four, card-native as it stands. */
+    pmf: ["Very disappointed", "Somewhat disappointed", "Not disappointed", "I no longer use IN2"]
+};
+/** The stored value for each rating label, so the mapping lives beside the labels it belongs to. */
+export const RATING_SCALE = { min: 1, max: 4 };
+/** How the two rating questions are put on a card: one line, both ends of the scale visible. */
+const cardLine = (n, question, options) => `  ${n}. "${question}" — one card, options ${options.map((o) => `\`${o}\``).join(" / ")}\n`;
+const bounded = (max) => z.string().trim().min(1).max(max);
+const severity = z
+    .enum(["blocked", "worked_around", "cosmetic"])
+    .describe("blocked = it stopped the run until a human or a workaround intervened; worked_around = it cost time or a detour but the run continued; cosmetic = wrong or confusing, no cost to the outcome.");
+const stage = z
+    .enum(TELEMETRY_STAGES)
+    .describe(`Where in the run it happened. THIS IS THE SAME VOCABULARY THE TIMING DATA USES, so your report joins the durations already recorded for that phase — do not invent a phase name. One of: ${TELEMETRY_STAGES.join(", ")}.`);
+const frictionPoint = z
+    .object({
+    severity,
+    stage: stage.optional(),
+    tool: bounded(FEEDBACK_LIMITS.tool).optional().describe("The tool involved, when there is one."),
+    citation: bounded(FEEDBACK_LIMITS.citation).describe("REQUIRED, and it must be a QUOTE: the exact error text, the doc passage, or the instruction line. Not a description of one. A friction point without a citation is the feedback equivalent of \"docs unclear\" and cannot be acted on. Replace any credential, activation code or token inside the quote with [REDACTED]."),
+    issue: bounded(FEEDBACK_LIMITS.issue).describe("What was wrong about it, in one or two sentences.")
+})
+    .strict();
+/** The record every path here produces, minus the fields the outbox and the grant fill in. */
+function draft(kind, source) {
+    return { eventId: newFeedbackId(), kind, source, createdAt: new Date().toISOString() };
+}
+function relay(result, what) {
+    if (result.recorded) {
+        return ok(`${what} recorded (${result.reportId}). It ships with this batch's other evidence at close.`, {
+            recorded: true,
+            reportId: result.reportId
+        });
+    }
+    if (result.unattributed) {
+        return fail("NO_BATCH_BOUND", result.reason ?? "no batch is bound to this run");
+    }
+    // Deliberately NOT an error result. This channel is fail-open by contract: a feedback tool that
+    // returned isError would put a reporting failure in front of the model mid-delivery, which is the
+    // one thing this must never cost.
+    return ok(`${what} could NOT be recorded (${result.reason ?? "unknown reason"}). The delivery is unaffected.`, {
+        recorded: false,
+        reason: result.reason
+    });
+}
+export function registerFeedbackTools(server, env = process.env) {
+    // The flag IS the registration. Subagent gating then comes free: analyzer skills condition on tool
+    // availability ("if report_feedback is among your tools…"), so tool presence is the flag and no
+    // per-install skill generation is needed.
+    if (!betaEnabled(env))
+        return;
+    server.registerTool("report_feedback", {
+        description: "RECORD IN THE IN2 DIAGNOSTICS QUEUE WHERE THIS RUN TRIPPED YOU UP. Beta only. Two ways to call it, and both are expected of every run.\n" +
+            "1. IN THE MOMENT, any time during the run: you hit a tool failure, an unexpected result, a doc that misled you, two instructions that conflicted, or a workflow that fought you. Call it THEN — a stumble reported while the exact error text is still in your context beats end-of-session recall, which reconstructs.\n" +
+            "2. AT CLOSE, on EVERY run, pass `wrapUp` instead: the run's own one-bit summary plus what actually happened. File it after the final writebacks, before `close_batch`.\n" +
+            "EVERY REPORT MUST CITE. Quote the specific error text, doc passage or instruction line you are complaining about — not a description of it. An uncited report is unactionable and will be read as noise.\n" +
+            "THREE GUARDRAILS, all absolute. (a) SYSTEM BEHAVIOUR ONLY: tool names, error codes, doc gaps, instruction conflicts, what you did about it — never the client org's content, and never the operator's words (those are theirs to give through record_operator_feedback). (b) REDACT SECRETS ALWAYS: replace any credential, activation code, session token or API key with [REDACTED], including inside quoted error text — quoted errors have carried live activation codes before. (c) NEVER NAME OR RECOMMEND A PERSON: this channel is the whole reporting path — if it is unavailable, summarize the IN2 error code for the operator and stop there; the delivery and `close_batch` continue; never name or recommend an individual, another MCP, or an external contact for an IN2 failure.\n" +
+            "A CLEAN PACKAGE WITH EMPTY LISTS IS A VALID AND VALUABLE REPORT; NEVER INVENT FRICTION. The clean-run wrap-up is the denominator — without it the trend can count failures but can never show the improving ratio. If nothing went wrong, say so with `ranCleanly: true` and an empty `frictionPoints`. Manufacturing a finding to look useful corrupts the only dataset that can tell whether this product is getting better.\n" +
+            "Identity is attached by the server from this batch's grant; there is nothing to name and nothing to get wrong.",
+        inputSchema: {
+            category: z
+                .enum(["tool_failure", "unexpected_result", "docs_gap", "instruction_conflict", "workflow_friction", "other"])
+                .optional()
+                .describe("What KIND of problem. Required for an in-the-moment report; omit when sending `wrapUp`."),
+            severity: severity.optional().describe("Required for an in-the-moment report; omit when sending `wrapUp`."),
+            stage: stage.optional(),
+            tool: bounded(FEEDBACK_LIMITS.tool).optional().describe("The tool involved, when there is one."),
+            errorCode: bounded(FEEDBACK_LIMITS.errorCode)
+                .optional()
+                .describe("The error code the tool actually returned (ORG_NOT_BOUND, LINT_BLOCKED, …), verbatim. It is the third leg of the fingerprint that groups your report with the same trip-up reported by other installs, so include it whenever there was one."),
+            role: bounded(FEEDBACK_LIMITS.role)
+                .optional()
+                .describe("Which agent is speaking: \"supervisor\", \"analyzer\", or another short label if neither fits."),
+            title: bounded(FEEDBACK_LIMITS.title).optional().describe("One line. Required for an in-the-moment report."),
+            body: bounded(FEEDBACK_LIMITS.body)
+                .optional()
+                .describe("What happened, expected vs actual, and what you did about it — QUOTING the error text, doc passage or instruction line. Required for an in-the-moment report."),
+            wrapUp: z
+                .object({
+                ranCleanly: z
+                    .boolean()
+                    .describe("The run's own one-bit summary: did this delivery go through without you having to work around anything?"),
+                frictionPoints: z
+                    .array(frictionPoint)
+                    .max(FEEDBACK_COUNTS.frictionPoints)
+                    .describe("Everything that tripped you up, each one cited. AN EMPTY ARRAY IS CORRECT AND EXPECTED for a clean run."),
+                wentWell: z
+                    .array(bounded(FEEDBACK_LIMITS.wentWell))
+                    .max(FEEDBACK_COUNTS.wentWell)
+                    .describe("Concrete things that worked, as one-liners — \"direct_lint caught the missing parent before the deploy\", not \"the tools were good\". This is what tells the developers which behaviours to protect across releases; friction without positives is a bug tracker, not an experience channel. An empty array is valid.")
+            })
+                .strict()
+                .optional()
+                .describe("The at-close package. Send this INSTEAD of category/severity/title/body, once per run, on every run.")
+        }
+    }, async (args) => {
+        try {
+            const { wrapUp, category, severity: sev, title, body, stage: at, tool, errorCode, role } = args;
+            const common = {
+                ...(at ? { stage: at } : {}),
+                ...(tool ? { tool } : {}),
+                ...(errorCode ? { errorCode } : {}),
+                ...(role ? { role } : {})
+            };
+            if (wrapUp) {
+                // Refused rather than merged. A call carrying both shapes is a model that has misread the
+                // tool, and quietly filing one of the two would hide that from it — and from the record.
+                if (category || sev || title || body) {
+                    return fail("FEEDBACK_SHAPE_CONFLICT", "Send either an in-the-moment report (category, severity, title, body) or the at-close wrapUp package, not both in one call. File the wrap-up on its own.");
+                }
+                return relay(recordFeedback({
+                    ...draft("wrap_up", "agent"),
+                    ...common,
+                    ranCleanly: wrapUp.ranCleanly,
+                    frictionPoints: wrapUp.frictionPoints,
+                    wentWell: wrapUp.wentWell
+                }), "Run wrap-up");
+            }
+            if (!category || !sev || !title || !body) {
+                return fail("FEEDBACK_INCOMPLETE", "An in-the-moment report needs category, severity, title and body — and the body must quote the specific error text, doc passage or instruction line. Alternatively send the at-close `wrapUp` package.");
+            }
+            return relay(recordFeedback({ ...draft("report", "agent"), ...common, category, severity: sev, title, body }), "Feedback");
+        }
+        catch (error) {
+            return internalError(error);
+        }
+    });
+    server.registerTool("record_operator_feedback", {
+        description: "RECORD WHAT THE OPERATOR SAID ABOUT THIS BATCH, IN THEIR OWN WORDS. Beta only. This tool has THREE shapes, asked at different moments; send exactly one of them per call.\n" +
+            "ASK AS ASKUSERQUESTION CARDS, ONE CARD PER RATING QUESTION. Never paste these as a form, never put them in prose, and never reword them. The operator answers by TAPPING an option; free text rides the card's built-in \"Other\", which is where an exact figure or an unlisted answer goes.\n" +
+            "AT CLOSE — ONCE per batch, AFTER the final Campfire writebacks and `close_batch`, the completed-value moment when they can see what they got:\n" +
+            cardLine(1, OPERATOR_QUESTIONS.ease, OPERATOR_OPTIONS.ease) +
+            cardLine(2, OPERATOR_QUESTIONS.satisfaction, OPERATOR_OPTIONS.satisfaction) +
+            cardLine(3, OPERATOR_QUESTIONS.open, OPERATOR_OPTIONS.open) +
+            "  On that third card the options are a PROMPT and \"Other\" is the real answer: if they tap an option, send that label as `openAnswer`; if they write, send their words. Either way it is what they gave you, never your gloss of it.\n" +
+            "  Pass `easeRating` and `satisfactionRating` as the NUMBER IN THE LABEL THEY TAPPED (1-4, 4 = best), and `openAnswer` as what they wrote.\n" +
+            `BEFORE THE FIRST DEPLOY — one card, immediately after they approve the execution plan: "${OPERATOR_QUESTIONS.manualEstimate}" with N replaced by the real requirement count, options ${OPERATOR_OPTIONS.manualEstimate.map((o) => `\`${o}\``).join(" / ")}, an exact figure through "Other". Send it as \`manualEstimate\`. ASK IT THERE AND NOWHERE ELSE — ASK IT PLAINLY, AND NEVER EXPLAIN TO THEM WHY IT IS ASKED THERE: the reason is a research-design argument, the operator did not ask for it, and narrating it is what made this card land as strange in QA.\n` +
+            `WHEN THE ACTIVATION SAID IT IS DUE — and only then — one further card at close: "${OPERATOR_QUESTIONS.pmf}", options ${OPERATOR_OPTIONS.pmf.map((o) => `\`${o}\``).join(" / ")}. Send it as \`pmfAnswer\`. If \`pmfDue\` was not set on this session, DO NOT ASK — the cadence is decided server-side.\n` +
+            "RECORD THEIR ACTUAL WORDS, NEVER A PARAPHRASE. `openAnswer` is what they wrote, verbatim, including how they said it. A summary of an operator's answer is your voice, not theirs, and it is worthless for the thing this exists to do. If they said more than one thing, put the rest in `additionalRemarks`, also verbatim.\n" +
+            "DECLINING IS FINE AND IS ALSO DATA. If they would rather not answer, do not press — call this with `declined: true` and nothing else. A recorded skip is a real answer about how much appetite there was at the end of that run; a silently unasked question is not.\n" +
+            "Identity is attached by the server from this batch's grant. Do not send any.",
+        inputSchema: {
+            easeRating: z
+                .number()
+                .int()
+                .min(RATING_SCALE.min)
+                .max(RATING_SCALE.max)
+                .optional()
+                .describe(`Their answer to "${OPERATOR_QUESTIONS.ease}" — the number in the option label they tapped: ${OPERATOR_OPTIONS.ease.join(", ")}.`),
+            satisfactionRating: z
+                .number()
+                .int()
+                .min(RATING_SCALE.min)
+                .max(RATING_SCALE.max)
+                .optional()
+                .describe(`Their answer to "${OPERATOR_QUESTIONS.satisfaction}" — the number in the option label they tapped: ${OPERATOR_OPTIONS.satisfaction.join(", ")}.`),
+            openAnswer: bounded(FEEDBACK_LIMITS.body)
+                .optional()
+                .describe(`Their answer to "${OPERATOR_QUESTIONS.open}", VERBATIM — their words, not your summary of them.`),
+            additionalRemarks: bounded(FEEDBACK_LIMITS.additionalRemarks)
+                .optional()
+                .describe("Anything else they said about the run, also verbatim."),
+            manualEstimate: z
+                .object({
+                bucket: z
+                    .enum(OPERATOR_OPTIONS.manualEstimate)
+                    .describe("The option they tapped, verbatim."),
+                exactMinutes: z
+                    .number()
+                    .int()
+                    .min(1)
+                    .max(FEEDBACK_BOUNDS.estimateMinutes)
+                    .optional()
+                    .describe("Only when they gave a figure through \"Other\" — in MINUTES. Still send the bucket their figure falls in; the bucket is what the trend is built on and the figure sharpens one batch."),
+                requirementCount: z
+                    .number()
+                    .int()
+                    .min(1)
+                    .max(FEEDBACK_BOUNDS.requirementCount)
+                    .describe("How many requirements the card actually named. Without it the answer cannot be normalised per requirement, which is the only way two batches compare.")
+            })
+                .strict()
+                .optional()
+                .describe(`The pre-execution answer to "${OPERATOR_QUESTIONS.manualEstimate}". Send it ALONE, immediately after plan approval and before the first deploy.`),
+            pmfAnswer: z
+                .enum(OPERATOR_OPTIONS.pmf)
+                .optional()
+                .describe(`Their answer to "${OPERATOR_QUESTIONS.pmf}", verbatim. ONLY when this session was activated with the due flag set — otherwise do not ask and do not send.`),
+            declined: z
+                .boolean()
+                .optional()
+                .describe("True when they chose not to answer. Send it alone; a declined ask is recorded as a skip.")
+        }
+    }, async ({ easeRating, satisfactionRating, openAnswer, additionalRemarks, manualEstimate, pmfAnswer, declined }) => {
+        try {
+            // THE THREE SHAPES ARE EXCLUSIVE, and a mixed call is refused rather than split — the same
+            // rule `report_feedback` applies to `wrapUp`. They are asked at different moments (the
+            // estimate before the first deploy, the rest at close), so a call carrying two of them is a
+            // model that has collapsed the timing this design exists to keep apart, and filing both
+            // would hide that from it and put a pre-registered counterfactual in the hindsight window.
+            const shapes = [
+                manualEstimate !== undefined ? "manualEstimate" : null,
+                pmfAnswer !== undefined ? "pmfAnswer" : null,
+                easeRating !== undefined || satisfactionRating !== undefined || openAnswer !== undefined || declined
+                    ? "the close ratings"
+                    : null
+            ].filter(Boolean);
+            if (shapes.length > 1) {
+                return fail("FEEDBACK_SHAPE_CONFLICT", `Send one shape per call, not ${shapes.join(" + ")}. The manual-time estimate is asked BEFORE the first deploy and the rest at close, so they are separate calls by design.`);
+            }
+            if (manualEstimate) {
+                return relay(recordFeedback({
+                    ...draft("manual_estimate", "operator"),
+                    estimateBucket: manualEstimate.bucket,
+                    ...(manualEstimate.exactMinutes !== undefined ? { estimateMinutes: manualEstimate.exactMinutes } : {}),
+                    requirementCount: manualEstimate.requirementCount
+                }), "Manual-time estimate");
+            }
+            if (pmfAnswer !== undefined) {
+                return relay(recordFeedback({ ...draft("pmf", "operator"), pmfAnswer }), "PMF answer");
+            }
+            if (declined) {
+                return relay(recordFeedback({ ...draft("operator", "operator"), declined: true }), "Declined feedback ask");
+            }
+            if (easeRating === undefined && satisfactionRating === undefined && openAnswer === undefined) {
+                return fail("FEEDBACK_EMPTY", "Nothing to record. Pass what the operator gave you — any of easeRating, satisfactionRating, openAnswer, manualEstimate or pmfAnswer — or `declined: true` if they chose not to answer.");
+            }
+            return relay(recordFeedback({
+                ...draft("operator", "operator"),
+                ...(easeRating !== undefined ? { easeRating } : {}),
+                ...(satisfactionRating !== undefined ? { satisfactionRating } : {}),
+                ...(openAnswer !== undefined ? { body: openAnswer } : {}),
+                ...(additionalRemarks !== undefined ? { additionalRemarks } : {})
+            }), "Operator feedback");
+        }
+        catch (error) {
+            return internalError(error);
+        }
+    });
+}

package/dist/tools/operator.js

@@ -0,0 +1,287 @@
+import path from "node:path";
+import { z } from "zod";
+import { isoNow } from "../core/ids.js";
+import { fail, internalError, ok } from "../core/result.js";
+import { WorkspaceError, fileExists, questionsDir, readJson, writeJsonAtomic } from "../core/workspace.js";
+import { CARD_LIMITS, QUESTIONS_SCHEMA_VERSION, WIRE_LIMITS, questionIdFor, statusFor, withQuestionIds } from "../core/operatorQa.js";
+import { loadSession } from "./session.js";
+import { emitDomainTelemetryEvent } from "../core/telemetryContext.js";
+// The consolidated operator-question surface, mirroring Claude Code's native
+// AskUserQuestion fields. The tool PERSISTS the card as a durable session
+// artifact and returns a rendered form for the harness to relay. Inside Claude
+// Code the supervisor mirrors the same card through the native AskUserQuestion
+// UI; on headless surfaces the persisted card IS the UI contract.
+//
+// THE ANSWER HALF. Until `record_operator_answers` this file recorded questions and nothing else:
+// the round file was written `PENDING` and no code path ever advanced it, so the status field was
+// dead state, a resumed session could not tell an open card from a settled one, and — the reason it
+// was noticed — what the operator actually CHOSE existed nowhere a reader could reach it. Answers
+// still reach the plan through `resolve_blocker` (that is what makes an authored file deployable),
+// but a plan blocker is a per-requirement edit, not a record of the card: one card question can
+// settle three requirements or none, so it can neither be found from a blocker nor reconstructed
+// from one. The two are complementary and both are required — `record_operator_answers` says what
+// was answered, `resolve_blocker` says what that answer changed.
+//
+// Everything recorded here is shipped at batch close by `core/operatorQa.ts`; the telemetry event
+// on the way past stays shape-only (counts, never text), exactly as `operator.question_presented`
+// always has.
+// EVERY CAP HERE IS THE LEDGER'S. `WIRE_LIMITS` mirrors `LIMITS` in
+// `apps/campfire-launch/convex/operatorQa.ts`; `CARD_LIMITS` are the stricter composition rules that
+// keep a card readable. These three fields were `z.string().min(1)` with no maximum while the ledger
+// capped them, so the model could compose a card that was accepted here and then refused — as a 400
+// for the whole request — at batch close, after the run, with no second attempt.
+const OptionSchema = z
+    .object({
+    label: z
+        .string()
+        .min(1)
+        .max(CARD_LIMITS.label)
+        .describe(`A short verdict ("OWD Private, keep the rule"), max ${CARD_LIMITS.label} chars — the reasoning goes in \`description\`.`),
+    description: z
+        .string()
+        .min(1)
+        .max(WIRE_LIMITS.description)
+        .describe(`What choosing this means, incl. trade-offs. Max ${WIRE_LIMITS.description} chars.`),
+    recommended: z.boolean().optional()
+})
+    .strict();
+const QuestionSchema = z
+    .object({
+    header: z.string().min(1).max(CARD_LIMITS.header).describe(`Chip label, max ${CARD_LIMITS.header} chars.`),
+    question: z.string().min(1).max(WIRE_LIMITS.question).describe(`Max ${WIRE_LIMITS.question} chars.`),
+    multiSelect: z.boolean().optional(),
+    options: z.array(OptionSchema).min(2).max(4)
+})
+    .strict();
+const AnswerSchema = z
+    .object({
+    questionId: z
+        .string()
+        .min(1)
+        .describe("Which question, as `ask_operator` returned it — r<round>q<n>, e.g. r1q2."),
+    chosenLabels: z
+        .array(z.string().min(1).max(WIRE_LIMITS.label))
+        .min(1)
+        .max(4)
+        .optional()
+        .describe("The option label(s) the operator picked, VERBATIM as the card offered them. One unless the question was multi-select."),
+    freeText: z
+        .string()
+        .min(1)
+        .max(WIRE_LIMITS.freeText)
+        .optional()
+        .describe(`What the operator said INSTEAD of picking an option — the 'Other' answer. Use this rather than inventing a label: chosenLabels must match the card, so an answer that was not on it belongs here. Max ${WIRE_LIMITS.freeText} chars.`)
+})
+    .strict();
+function roundFile(sessionId, round) {
+    return path.join(questionsDir(sessionId), `${String(round).padStart(4, "0")}.json`);
+}
+export function registerOperatorTools(server) {
+    server.registerTool("ask_operator", {
+        description: "Persist the consolidated operator question card (the ONE question round per phase). Refuses on `RECOMMENDED_OPTION_REQUIRED`. " +
+            "CARDS SPEAK THE OPERATOR'S LANGUAGE: Salesforce vocabulary and business consequences, never harness internals — no raw verdict names, no wave/lint/checkOnly/projection words, no file paths; mechanism belongs in option descriptions, one clause at most. See reference/operator-voice.md. " +
+            "Returns the rendered card AND a stable id per question (r<round>q<n>); relay the card to the operator (in Claude Code, mirror it through the native AskUserQuestion UI) and STOP — never continue past an unanswered card, and never end a working turn with prose instead of a card. " +
+            "ASK ONLY WHAT CHANGES THE WORK. A question whose recommended answer you would proceed with anyway is an ASSUMPTION — state it in the approval card as an assumption in force, do not spend a round-trip on it. Every round costs real operator wait. The test is LIKELY DISSENT, never the text's silence: card it only when a reasonable operator might pick the other option (business meaning, data risk, anything irreversible). Display cosmetics, a spec reading where both readings hold every real value, a platform default the requirement does not contradict — assumptions, all of them. \"It deviates from the literal text\" is not by itself a reason to ask. " +
+            "Once answered: `record_operator_answers` with the ids this call returned, then `resolve_blocker` to record the consequence on plan.json — writeback is built from the plan, so an answer that never reaches it leaves the question reading as open.",
+        inputSchema: {
+            sessionId: z.string(),
+            round: z
+                .number()
+                .int()
+                .positive()
+                .describe("Question round number within the session (1 = the consolidated round, 2 = a narrow corrective re-ask, ...)."),
+            questions: z.array(QuestionSchema).min(1).max(4)
+        }
+    }, async ({ sessionId, round, questions }) => {
+        try {
+            await loadSession(sessionId);
+            for (const [index, question] of questions.entries()) {
+                const recommended = question.options.filter((option) => option.recommended === true);
+                if (recommended.length !== 1) {
+                    return fail("RECOMMENDED_OPTION_REQUIRED", `questions[${index}] has ${recommended.length} recommended options; exactly one is required — the operator's default action is confirming your recommendation.`);
+                }
+            }
+            const file = roundFile(sessionId, round);
+            if (fileExists(file)) {
+                // A ROUND NUMBER IS WRITE-ONCE. Everything below this line overwrites the round file
+                // wholesale, so any existing round must refuse rather than fall through — a settled round
+                // that fell through lost the operator's recorded choices for good, since the upload happens
+                // at close and reads whatever the file says by then.
+                //
+                // Derived, not trusted: a v1 file recorded no `status`, and a stored one that disagrees
+                // with its own questions must not be what decides whether an answer can be destroyed.
+                const existing = await readJson(file);
+                const status = existing.status ?? statusFor(existing.questions ?? []);
+                if (status === "PENDING") {
+                    return fail("ROUND_ALREADY_PENDING", `Question round ${round} is already pending at ${file}; do not re-ask — wait for the operator, then record what they said with record_operator_answers.`);
+                }
+                return fail("ROUND_ALREADY_ANSWERED", `Question round ${round} is ${status} at ${file} — re-asking it would overwrite what the operator already chose. ` +
+                    `To ask again, use a NEW round number (round ${round + 1}); a corrective re-ask is a new round, never an edit of a settled one.`);
+            }
+            // The id is DERIVED from position (questionIdFor), not minted, so it is stable across a
+            // re-read and identical to what a round file written before ids existed would address.
+            const persisted = questions.map((question, index) => ({
+                ...question,
+                questionId: questionIdFor(round, index)
+            }));
+            await writeJsonAtomic(file, {
+                schemaVersion: QUESTIONS_SCHEMA_VERSION,
+                round,
+                askedAt: isoNow(),
+                status: "PENDING",
+                questions: persisted
+            });
+            emitDomainTelemetryEvent("operator.question_presented", { questionCount: questions.length }, { stage: "operator-gate", outcome: "presented" });
+            const rendered = questions
+                .map((question, index) => {
+                const options = question.options
+                    .map((option, optionIndex) => `  ${optionIndex + 1}. ${option.label}${option.recommended ? " (Recommended)" : ""} — ${option.description}`)
+                    .join("\n");
+                return `${index + 1}/${questions.length} [${question.header}] ${question.question}${question.multiSelect ? " (multi-select)" : ""}\n${options}`;
+            })
+                .join("\n\n");
+            // The ids sit BELOW the card rather than inside it: the block above is relayed verbatim to a
+            // non-technical operator, and `r1q2` means nothing to them.
+            const ids = persisted
+                .map((question, index) => `  ${question.questionId} = ${index + 1}/${questions.length} [${question.header}]`)
+                .join("\n");
+            return ok(`question round ${round} persisted -> ${file}\nRelay this card to the operator and STOP:\n\n${rendered}\n\n` +
+                `When they answer, call record_operator_answers {sessionId, round: ${round}, answers: [...]} using these ids:\n${ids}`, {
+                file,
+                round,
+                questionCount: questions.length,
+                questionIds: persisted.map((question) => question.questionId)
+            });
+        }
+        catch (error) {
+            if (error instanceof WorkspaceError)
+                return fail(error.code, error.message);
+            return internalError(error);
+        }
+    });
+    server.registerTool("record_operator_answers", {
+        title: "Record what the operator answered on a question card",
+        description: "Close a question round with what the operator actually said. Call it as soon as they answer, BEFORE acting on the answer and before resolve_blocker — it is what turns a card from open to settled, and the only record of WHICH option they took. One call may answer several questions or one; refuses on `UNKNOWN_OPTION` and `QUESTION_ALREADY_ANSWERED`. " +
+            "This does not change the plan — `resolve_blocker` still records the consequence on requirements/<extId>/plan.json, and both are required: this says what was ANSWERED, that says what it CHANGED.",
+        inputSchema: {
+            sessionId: z.string(),
+            round: z.number().int().positive().describe("The round being answered, as passed to ask_operator."),
+            answers: z.array(AnswerSchema).min(1).max(4)
+        }
+    }, async ({ sessionId, round, answers }) => {
+        try {
+            await loadSession(sessionId);
+            const file = roundFile(sessionId, round);
+            if (!fileExists(file)) {
+                return fail("QUESTION_ROUND_NOT_FOUND", `Session ${sessionId} has no question round ${round}. Rounds are created by ask_operator; check the round number it returned.`);
+            }
+            const stored = await readJson(file);
+            const questions = withQuestionIds(stored);
+            const known = new Map(questions.map((question) => [question.questionId, question]));
+            // RESOLVE EVERY ANSWER BEFORE WRITING ANYTHING. Each refusal below promises the round was
+            // left untouched; addressing first is what makes that true of the in-memory document too,
+            // so a half-recorded round cannot exist even transiently. Same discipline as resolve_blocker.
+            const seen = new Set();
+            const resolved = [];
+            for (const answer of answers) {
+                const question = known.get(answer.questionId);
+                if (!question) {
+                    return fail("QUESTION_NOT_FOUND", `Round ${round} has no question "${answer.questionId}". Present: ${questions.map((q) => `${q.questionId} [${q.header}]`).join(", ")}. Nothing was recorded.`);
+                }
+                if (seen.has(answer.questionId)) {
+                    return fail("DUPLICATE_ANSWER", `${answer.questionId} is answered twice in one call, so this call would record an answer it cannot keep. Nothing was recorded.`);
+                }
+                seen.add(answer.questionId);
+                if (question.answer) {
+                    return fail("QUESTION_ALREADY_ANSWERED", `Round ${round} question ${answer.questionId} is already answered: ${describeAnswer(question)}. Recording a second answer would lose the first; ask a corrective round instead. Nothing was recorded.`);
+                }
+                if (!answer.chosenLabels?.length && !answer.freeText) {
+                    return fail("ANSWER_REQUIRED", `${answer.questionId} carries neither chosenLabels nor freeText, which records that something was answered and nothing about what. Nothing was recorded.`);
+                }
+                const labels = new Set((question.options ?? []).map((option) => option.label));
+                const unknownLabel = (answer.chosenLabels ?? []).find((label) => !labels.has(label));
+                if (unknownLabel !== undefined) {
+                    return fail("UNKNOWN_OPTION", `${answer.questionId} was answered "${unknownLabel}", which the card did not offer. Options: ${[...labels].join(" | ")}. If the operator said something else, pass it as freeText — chosenLabels must match the card or the record stops being queryable. Nothing was recorded.`);
+                }
+                if (!question.multiSelect && (answer.chosenLabels?.length ?? 0) > 1) {
+                    return fail("SINGLE_SELECT_QUESTION", `${answer.questionId} was not multi-select, so it cannot carry ${answer.chosenLabels.length} chosen options. Nothing was recorded.`);
+                }
+                resolved.push({ index: questions.indexOf(question), answer });
+            }
+            const at = isoNow();
+            const updated = questions.map((question) => ({ ...question }));
+            for (const { index, answer } of resolved) {
+                updated[index] = {
+                    ...updated[index],
+                    answer: {
+                        chosenLabels: answer.chosenLabels ?? [],
+                        ...(answer.freeText ? { freeText: answer.freeText } : {}),
+                        answeredAt: at
+                    }
+                };
+            }
+            const status = statusFor(updated);
+            await writeJsonAtomic(file, {
+                ...stored,
+                schemaVersion: QUESTIONS_SCHEMA_VERSION,
+                round,
+                questions: updated,
+                status,
+                // Stamped only when the round is complete: a half-answered round has no answered time, and
+                // claiming one would make an open gate look settled to every later reader.
+                ...(status === "ANSWERED" ? { answeredAt: at } : {})
+            });
+            // SHAPE ONLY, deliberately. The counts ride the event stream, which stays free of prose; the
+            // text goes out at batch close by its own route. `recommendedCount` is the one worth having
+            // centrally — CF74's "18 of 19 answered with the recommendation" was a hand count off one
+            // run's local files, and it is the number that says whether a card round was worth its wait.
+            const answered = updated.filter((question) => question.answer !== undefined);
+            emitDomainTelemetryEvent("operator.answers_recorded", {
+                round,
+                questionCount: updated.length,
+                answeredCount: answered.length,
+                freeTextCount: answered.filter((question) => question.answer?.freeText !== undefined).length,
+                recommendedCount: answered.filter((question) => tookRecommendation(question)).length
+            }, { stage: "operator-gate", outcome: status === "ANSWERED" ? "answered" : "partial" });
+            const open = updated.length - answered.length;
+            return ok([
+                `round ${round} recorded ${resolved.length} answer(s) -> ${file}`,
+                ...resolved.map(({ index }) => `  ${updated[index].questionId} [${updated[index].header}] ${describeAnswer(updated[index])}`),
+                open > 0
+                    ? `  ${open} question(s) in this round still unanswered.`
+                    : "  every question in this round is answered.",
+                "",
+                "Now record what the answer CHANGED: resolve_blocker on each affected requirement, or re-run",
+                "that analyzer when the answer changes which components exist."
+            ].join("\n"), {
+                round,
+                status,
+                recorded: resolved.length,
+                answeredCount: answered.length,
+                openCount: open
+            });
+        }
+        catch (error) {
+            if (error instanceof WorkspaceError)
+                return fail(error.code, error.message);
+            return internalError(error);
+        }
+    });
+}
+/** Did the operator simply confirm the recommendation? Exactly one choice, and it is the recommended one. */
+function tookRecommendation(question) {
+    const recommended = (question.options ?? []).find((option) => option.recommended === true);
+    const chosen = question.answer?.chosenLabels ?? [];
+    return recommended !== undefined && chosen.length === 1 && chosen[0] === recommended.label;
+}
+function describeAnswer(question) {
+    const answer = question.answer;
+    if (!answer)
+        return "(unanswered)";
+    const parts = [];
+    if (answer.chosenLabels.length > 0)
+        parts.push(answer.chosenLabels.join(" + "));
+    if (answer.freeText)
+        parts.push(`free text: ${answer.freeText}`);
+    return parts.join("; ");
+}