@dungle-scrubs/harness-cli-normalizer 0.4.1 → 0.4.2

package/src/cli/help.ts

@@ -42,6 +42,12 @@ Options:
   --no-write                Disable write
   --shell                   Enable shell (muse)
   --no-shell                Disable shell
+  --escalate-questions      Let the worker ask the caller's user when a
+                            genuine decision blocks progress (DEFAULT;
+                            prompt-preamble transport, question event +
+                            done cause "awaiting-input", exit 0)
+  --no-escalate-questions   Worker never asks: it states the assumption it
+                            proceeded under and continues
   --max-steps <n>           Max steps (muse, 1-10000)
   --timeout <seconds>       Wall-clock budget for the run (all harnesses,
                             hcn-enforced; 0 disables; no default)
@@ -51,7 +57,11 @@ Options:
   --no-skills               Disable skills discovery facet
   --cwd <path>              Working directory for spawn
   --env KEY=VAL             Environment (repeatable; KEY= deletes)
-  --resume <uuid>           Resume session id (UUID)
+  --resume <uuid>           Resume session id (UUID). The answer path for
+                            question escalation: resume with the chosen
+                            answer as the prompt; id continuity per
+                            harness (claude stable, pi/muse caller-assigned,
+                            codex minted via identity event)
   --                        Passthrough: native harness args verbatim
                             (failures surface as labeled native errors)
   --json                    NDJSON HarnessEvent to stdout
@@ -64,7 +74,9 @@ Defaults with no flags:
   > harness default. The profile pins: effort medium, sandbox
   workspace-write (codex only; other harnesses report divergence),
   discovery on, autonomy off, write/shell on. timeout and max-steps have
-  no default. Provenance prints to stderr on every run; see
+  no default. Question escalation defaults ON (config key
+  "escalateQuestions"; it is a prompt preamble, never a harness flag).
+  Provenance prints to stderr on every run; see
   'hcn inspect <harness>' for the resolved argv of a bare run.
 `;
 
@@ -102,8 +114,13 @@ Options:
   --autonomy / --no-autonomy
   --write / --no-write
   --shell / --no-shell
+  --escalate-questions / --no-escalate-questions
+                            (accepted; renders nothing - rides the run prompt)
   --max-steps <n>
   --no-tools, --no-instruction-files, --no-extensions, --no-skills
+  --escalate-questions / --no-escalate-questions
+                            Accepted; renders nothing in argv (the mode
+                            rides the run prompt, not a harness flag)
   --cwd <path>
   --env KEY=VAL
   --resume <uuid>

package/src/cli/render.ts

@@ -4,6 +4,7 @@ const dim = (s: string) => `\x1b[2m${s}\x1b[0m`;
 const cyan = (s: string) => `\x1b[36m${s}\x1b[0m`;
 const green = (s: string) => `\x1b[32m${s}\x1b[0m`;
 const red = (s: string) => `\x1b[31m${s}\x1b[0m`;
+const blue = (s: string) => `\x1b[34m${s}\x1b[0m`;
 const yellow = (s: string) => `\x1b[33m${s}\x1b[0m`;
 
 export interface RenderState {
@@ -36,6 +37,15 @@ export const renderEvent = (event: HarnessEvent, state: RenderState): void => {
     case "limit":
       process.stdout.write(yellow(`\n  ⚠ limit: ${event.code} ${event.message}`));
       break;
+    case "question":
+      // issue #41: the structured question fields ARE the question - this
+      // render is a convenience view of them, not the contract.
+      process.stdout.write(blue(`\n  ? ${event.question}\n`));
+      for (const option of event.options) {
+        const mark = option === event.recommended ? "*" : " ";
+        process.stdout.write(blue(`    ${mark} ${option}\n`));
+      }
+      break;
     case "error":
       process.stdout.write(red(`\n  ✗ ${event.message}`));
       break;
@@ -54,7 +64,12 @@ export const renderEvent = (event: HarnessEvent, state: RenderState): void => {
       break;
     }
     case "done": {
-      const mark = event.cause === "clean" ? green("○ clean") : red(`○ ${event.cause}`);
+      const mark =
+        event.cause === "clean" || event.cause === "awaiting-input"
+          ? event.cause === "awaiting-input"
+            ? blue("○ awaiting input")
+            : green("○ clean")
+          : red(`○ ${event.cause}`);
       const tail = event.failure ? ` ${event.failure.class}: ${event.failure.message}` : "";
       process.stdout.write(`\n  ${mark} (exit ${event.exitCode ?? "none"})${tail}\n`);
       break;

package/src/cli/run.ts

@@ -2,12 +2,9 @@ import type { HarnessEvent } from "../execution/events.js";
 import { nodeRunnerDeps } from "../execution/node-deps.js";
 import { KILL_GRACE_MS, redactArgv, streamTurn } from "../execution/stream-turn.js";
 import { buildLaunchArgv, buildResumeArgv } from "../interpretation/argv.js";
+import { composeEscalatedPrompt } from "../interpretation/question.js";
 import { ArgvRefusalError } from "../interpretation/refusal.js";
-import {
-  FloorExceededError,
-  type ProvenanceEntry,
-  resolveEffectiveOptions,
-} from "../interpretation/resolve-options.js";
+import { FloorExceededError, resolveEffectiveOptions } from "../interpretation/resolve-options.js";
 import { recognizeNativeSpelling, supportedBy } from "../interpretation/support.js";
 import { defaultDescriptors } from "../knowledge/overrides.js";
 import { parseRunExtra, parseTurnOptions, resolvePromptAsync } from "./args.js";
@@ -213,15 +210,18 @@ export const run = async (harnessName: string, rawArgs: string[]): Promise<void>
 
   // Defaults profile + user config: LAUNCH-ONLY. A resumed session keeps
   // its own settings; the resolver never runs on resume paths.
-  let resolvedProvenance: readonly ProvenanceEntry[] = [];
-  let resolvedUnrenderable: readonly string[] = [];
   let effectiveTurnOpts: ReturnType<typeof parseTurnOptions> = turnOpts;
   const resolvedTiers: {
     user?: Partial<ReturnType<typeof parseTurnOptions>>;
     project?: Partial<ReturnType<typeof parseTurnOptions>>;
   } = {};
-  if (extra.resume === undefined) {
-    const tiers = resolvedTiers;
+  // Config files load on EVERY run, launch or resume: the tiers feed the
+  // defaults profile on launch, and issue #41's escalateQuestions (a
+  // behavior instruction, not a turn option) resolves from them on resume
+  // too - otherwise a no-escalate session would flip its preamble on the
+  // answer turn. Resolution of TURN options stays launch-only.
+  const tiers = resolvedTiers;
+  {
     const { loadUserConfig, loadProjectConfig, ConfigError } = await import("./config.js");
     try {
       const loaded = loadUserConfig();
@@ -236,6 +236,8 @@ export const run = async (harnessName: string, rawArgs: string[]): Promise<void>
       }
       throw configErr;
     }
+  }
+  if (extra.resume === undefined) {
     let resolved: ReturnType<typeof resolveEffectiveOptions>;
     try {
       resolved = resolveEffectiveOptions(h, { ...turnOpts, prompt } as never, tiers);
@@ -248,8 +250,6 @@ export const run = async (harnessName: string, rawArgs: string[]): Promise<void>
       throw resErr;
     }
     const { provenance, unrenderable } = resolved;
-    resolvedProvenance = provenance;
-    resolvedUnrenderable = unrenderable;
     const { prompt: _p, ...rest } = resolved.options as { prompt: string };
     effectiveTurnOpts = rest as ReturnType<typeof parseTurnOptions>;
     // Provenance is diagnostic data like the spawn line - stderr in BOTH
@@ -268,12 +268,39 @@ export const run = async (harnessName: string, rawArgs: string[]): Promise<void>
     }
   }
 
+  // issue #41: question-escalation precedence arg > project > user >
+  // default-true (a behavior instruction, not a turn option - the
+  // default lives OUTSIDE the profile on purpose, per the spec). It
+  // applies on LAUNCH AND RESUME alike: it shapes each turn's prompt
+  // preamble and event stream, never a session setting.
+  const projectEscalate = (resolvedTiers.project as { escalateQuestions?: boolean } | undefined)
+    ?.escalateQuestions;
+  const userEscalate = (resolvedTiers.user as { escalateQuestions?: boolean } | undefined)
+    ?.escalateQuestions;
+  const escalateQuestions =
+    turnOpts.escalateQuestions !== undefined
+      ? turnOpts.escalateQuestions
+      : projectEscalate !== undefined
+        ? projectEscalate
+        : userEscalate !== undefined
+          ? userEscalate
+          : true;
+  const escalateTier =
+    turnOpts.escalateQuestions !== undefined
+      ? "arg"
+      : projectEscalate !== undefined
+        ? "project-config"
+        : userEscalate !== undefined
+          ? "user-config"
+          : "default";
+
   const fullOpts = {
     ...effectiveTurnOpts,
-    prompt,
+    prompt: composeEscalatedPrompt(prompt, escalateQuestions),
     cwd: extra.cwd,
     env: extra.env,
     resume: extra.resume,
+    escalateQuestions,
     ...(passthrough.length > 0 ? { passthrough } : {}),
     ...(isExplicit ? { __explicitPrompt: true as const } : {}),
   } as Parameters<typeof streamTurn>[1] & {
@@ -287,20 +314,23 @@ export const run = async (harnessName: string, rawArgs: string[]): Promise<void>
   let preArgv: string[] | null = null;
   try {
     if (fullOpts.resume) {
-      // Resume never carries profile/config resolution (launch-only rule),
-      // so it builds from the raw turn options.
+      // Resume never carries TURN-option profile resolution (launch-only
+      // rule), so it builds from the raw turn options; hcn-owned behavior
+      // (escalateQuestions preamble, timeout budget) still applies.
       preArgv = buildResumeArgv(h, {
         ...(turnOpts as object),
-        prompt,
+        prompt: fullOpts.prompt,
         sessionId: fullOpts.resume,
         __explicitPrompt: isExplicit,
       } as never);
     } else {
       // Launch builds from the RESOLVED options so the spawn line and the
-      // real argv agree.
+      // real argv agree. The prompt here is the COMPOSED one (escalation
+      // preamble included) - redactArgv masks by position, so an argv
+      // built from the raw prompt would leak it into the spawn line.
       preArgv = buildLaunchArgv(h, {
         ...(effectiveTurnOpts as object),
-        prompt,
+        prompt: fullOpts.prompt,
         __explicitPrompt: isExplicit,
       } as never);
       const claudeSkillTokens = (effectiveTurnOpts as unknown as { __claudeSkillTokens?: string[] })
@@ -330,13 +360,18 @@ export const run = async (harnessName: string, rawArgs: string[]): Promise<void>
   // since buildLaunchArgv now respects __explicitPrompt.
 
   if (preArgv) {
-    const redacted = redactArgv(preArgv, prompt);
+    const redacted = redactArgv(preArgv, fullOpts.prompt);
     if (!wantJson) {
       process.stderr.write(`spawn: ${redacted.join(" ")}\n`);
     } else {
       // In JSON mode, diagnostics to stderr only
       process.stderr.write(`spawn: ${redacted.join(" ")}\n`);
     }
+    // issue #41: the escalation mode rides stderr as provenance, like
+    // every other resolution the turn depends on.
+    process.stderr.write(
+      `provenance: escalateQuestions = ${escalateQuestions} (${escalateTier})\n`,
+    );
   }
 
   // Delete HERDR_ENV before spawn
@@ -413,7 +448,7 @@ export const run = async (harnessName: string, rawArgs: string[]): Promise<void>
         renderEvent(event, state);
       }
       if (event.kind === "done") {
-        if (event.cause === "clean") exitCode = 0;
+        if (event.cause === "clean" || event.cause === "awaiting-input") exitCode = 0;
         else exitCode = 1;
         // If failure class is rejected? But done.cause for rejected would be failed? Still 1 per mapping, but refusal before spawn is 2.
         // The RFC says limit/auth ->1, transport ->1, refusal ->2 (already handled). So done non-clean =>1.

package/src/execution/events.ts

@@ -17,7 +17,16 @@
 import type { CapabilityResult } from "../interpretation/capabilities.js";
 import type { FailureSummary } from "./failure.js";
 
-export type ExitCause = "clean" | "limit" | "crash" | "stall" | "killed" | "failed";
+export type ExitCause =
+  | "clean"
+  | "limit"
+  | "crash"
+  | "stall"
+  | "killed"
+  | "failed"
+  /** issue #41: the turn ended by asking (escalateQuestions) - a
+   * SUCCESSFUL turn (process exit 0); the caller resumes with the answer. */
+  | "awaiting-input";
 
 export type HarnessEvent =
   | {
@@ -31,6 +40,15 @@ export type HarnessEvent =
   | { readonly kind: "progress"; readonly label: string }
   | { readonly kind: "tool"; readonly name: string; readonly input?: unknown }
   | { readonly kind: "context"; readonly usedPct: number }
+  | {
+      /** issue #41: the worker asked the caller's user a question (the
+       * final message carried an hcn-question block). Structured-first:
+       * these fields ARE the question; prose renders from them. */
+      readonly kind: "question";
+      readonly question: string;
+      readonly options: readonly string[];
+      readonly recommended?: string;
+    }
   | { readonly kind: "limit"; readonly code: string; readonly message: string }
   | { readonly kind: "error"; readonly message: string }
   | ({ readonly kind: "failure" } & FailureSummary)

package/src/execution/stream-turn.ts

@@ -17,6 +17,7 @@ import {
 } from "../interpretation/argv.js";
 import { stdinPolicyOf } from "../interpretation/dimensions.js";
 import { detectAuthFailureInLine, detectLimitInLine } from "../interpretation/limits.js";
+import { composeEscalatedPrompt, detectQuestionBlock } from "../interpretation/question.js";
 import { ArgvRefusalError } from "../interpretation/refusal.js";
 import type { HarnessDescriptor } from "../knowledge/descriptor.js";
 import { matcherOverridesOf } from "../knowledge/overrides.js";
@@ -102,6 +103,13 @@ export interface TurnRunOptions extends LaunchOptions {
    * normalized argv. Wrong-harness flags here fail in the harness itself
    * and surface as native errors - hcn never validates them. */
   readonly passthrough?: readonly string[];
+  /** issue #41: question escalation (behavior instruction, NOT a turn
+   * option - no flag ever reaches the harness). True (the default when
+   * undefined) prepends the protocol preamble and arms question-block
+   * detection; false prepends the state-the-assumption instruction and
+   * disarms detection. Applies on launch AND resume: it shapes each
+   * turn's prompt and event stream, never a session setting. */
+  readonly escalateQuestions?: boolean;
 }
 
 export async function* streamTurn(
@@ -112,6 +120,21 @@ export async function* streamTurn(
   const turnId = deps.turnId ?? `turn-${++turnCounter}`;
   const log = deps.log ?? (() => {});
 
+  // issue #41: compose the escalation preamble onto the prompt (the
+  // transport IS the prompt - no harness has native question conveyance)
+  // and arm detection in the true mode. Composition is idempotent, so a
+  // caller that already composed (the CLI does, for spawn-line truth)
+  // never double-prepends.
+  const escalateQuestions = opts.escalateQuestions !== false;
+  const effective: TurnRunOptions = {
+    ...opts,
+    prompt: composeEscalatedPrompt(opts.prompt, escalateQuestions),
+  };
+  // The turn's last assistant message - where the protocol says the
+  // hcn-question block lives. Tracked only when detection is armed.
+  let lastAssistantText: string | null = null;
+  let asked = false;
+
   // Validate env before building argv so an invalid env is a refusal, not a spawn
   if (opts.env !== undefined) {
     for (const [k, v] of Object.entries(opts.env)) {
@@ -134,7 +157,7 @@ export async function* streamTurn(
           harness: h.name,
           issue: refusal.issue,
           supported: refusal.supported,
-          argv: redactArgv([], opts.prompt),
+          argv: redactArgv([], effective.prompt),
         });
         yield { kind: "failure", ...failure };
         yield { kind: "done", exitCode: null, cause: "failed", failure };
@@ -147,11 +170,11 @@ export async function* streamTurn(
   let granularity: import("../knowledge/descriptor.js").StreamingGranularity;
   try {
     argv =
-      opts.resume === undefined
-        ? buildLaunchArgv(h, opts)
-        : buildResumeArgv(h, { ...opts, sessionId: opts.resume });
-    if (opts.passthrough !== undefined && opts.passthrough.length > 0) {
-      argv = [...argv, "--", ...opts.passthrough];
+      effective.resume === undefined
+        ? buildLaunchArgv(h, effective)
+        : buildResumeArgv(h, { ...effective, sessionId: effective.resume });
+    if (effective.passthrough !== undefined && effective.passthrough.length > 0) {
+      argv = [...argv, "--", ...effective.passthrough];
     }
     // issue #38: claude renders the skills allowlist as settings JSON at
     // the argv tail (the complement-off form).
@@ -175,7 +198,7 @@ export async function* streamTurn(
       // No process spawned on a refusal - log rejected instead of spawn
       let argvForLog: string[] = [];
       try {
-        argvForLog = redactArgv([], opts.prompt);
+        argvForLog = redactArgv([], effective.prompt);
       } catch {}
       log({
         event: "rejected",
@@ -200,7 +223,7 @@ export async function* streamTurn(
     event: "spawn",
     turnId,
     harness: h.name,
-    argv: redactArgv(argv, opts.prompt),
+    argv: redactArgv(argv, effective.prompt),
     granularity,
     ...(matcherOverrides ? { matcherOverrides } : {}),
     ...(envKeys?.length ? { envKeys } : {}),
@@ -210,8 +233,8 @@ export async function* streamTurn(
   try {
     proc = deps.spawn(argv, {
       stdin: stdinPolicyOf(h) === "close-required" ? "close" : "inherit",
-      ...(opts.cwd !== undefined ? { cwd: opts.cwd } : {}),
-      ...(opts.env !== undefined ? { env: opts.env } : {}),
+      ...(effective.cwd !== undefined ? { cwd: effective.cwd } : {}),
+      ...(effective.env !== undefined ? { env: effective.env } : {}),
     });
   } catch (cause) {
     // Spawn failure is a transport failure, not merely a crash
@@ -232,7 +255,7 @@ export async function* streamTurn(
   }
 
   const queue = new AsyncChannel<HarnessEvent>();
-  const state = freshDecodeState(opts.resume ?? null);
+  const state = freshDecodeState(effective.resume ?? null);
   const stderrTail = new StderrTail();
   let killedByWatchdog = false;
   let exited = false;
@@ -341,6 +364,9 @@ export async function* streamTurn(
             // Directly from decode's rate_limit_event handling - track for reduction
             failures.push(event as unknown as FailureSummary);
           }
+          if (escalateQuestions && event.kind === "message" && event.role === "assistant") {
+            lastAssistantText = event.text;
+          }
           await queue.push(event);
         }
       }
@@ -356,6 +382,37 @@ export async function* streamTurn(
     }
   };
 
+  /** issue #41: scan the last assistant message for the hcn-question
+   * block. Structured-first - the block's fields become the event; no
+   * prose parsing. Runs after the pumps settle (the last message is only
+   * last then) and only when detection is armed (escalateQuestions
+   * true). A malformed block surfaces as an error event, never a silent
+   * no-op. */
+  const emitQuestionIfAsked = async (): Promise<void> => {
+    if (!escalateQuestions || lastAssistantText === null) return;
+    const detection = detectQuestionBlock(lastAssistantText);
+    if (detection === null) return;
+    if ("malformed" in detection) {
+      await queue.push({ kind: "error", message: detection.malformed });
+      return;
+    }
+    log({
+      event: "question",
+      turnId,
+      harness: h.name,
+      options: detection.block.options.length,
+    });
+    asked = true;
+    await queue.push({
+      kind: "question",
+      question: detection.block.question,
+      options: detection.block.options,
+      ...(detection.block.recommended !== undefined
+        ? { recommended: detection.block.recommended }
+        : {}),
+    });
+  };
+
   const pumpStderr = async (): Promise<void> => {
     const lines = new LineBuffer();
     for await (const chunk of proc.stderr) {
@@ -413,7 +470,9 @@ export async function* streamTurn(
     observePump("stdout", pumpStdout()),
     observePump("stderr", pumpStderr()),
   ]);
-  void Promise.all([proc.exited, pumpSettlements]).then(() => queue.close());
+  void Promise.all([proc.exited, pumpSettlements])
+    .then(() => emitQuestionIfAsked())
+    .then(() => queue.close());
 
   try {
     for await (const event of queue) yield event;
@@ -459,7 +518,9 @@ export async function* streamTurn(
           ? "killed" // D11: the run was killed on budget, not stalled
           : "stall"
         : exitCode === 0
-          ? "clean"
+          ? asked
+            ? "awaiting-input" // issue #41: asking SUCCEEDED the turn
+            : "clean"
           : exitCode === null
             ? "killed"
             : "crash";

package/src/interpretation/argv.ts

@@ -69,6 +69,11 @@ export interface TurnOptions {
   readonly write?: boolean;
   readonly shell?: boolean;
   readonly maxSteps?: number;
+  /** issue #41: question escalation - a BEHAVIOR INSTRUCTION, not a turn
+   * option. It never renders into any harness argv; the CLI layer turns
+   * it into the prompt preamble and arms question-block detection.
+   * Undefined means the default: true. */
+  readonly escalateQuestions?: boolean;
   /** Internal: set by CLI when prompt came from --prompt/--prompt-file to bypass leading '-' guard */
   readonly __explicitPrompt?: boolean;
 }

package/src/interpretation/question.ts

@@ -0,0 +1,137 @@
+/**
+ * Question escalation (issue #41): the protocol that lets a headless
+ * worker ask the CALLER's user a question. Transport is the prompt - no
+ * harness ships native question conveyance - so hcn prepends a protocol
+ * contract (escalateQuestions true, the default) or the state-the-
+ * assumption instruction (false). The worker's final message then carries
+ * a fenced `hcn-question` block; detection is structured-first (fields
+ * parsed from the block, prose rendered downstream from them).
+ *
+ * Ratified design note (2026-08-19): autonomy and escalateQuestions are
+ * independent flags carving the same substrate by ORIGIN - autonomy =
+ * interrupts the harness raises (permission gates), escalateQuestions =
+ * interrupts the model raises (judgment gaps). The true-mode preamble
+ * must therefore never conflate asking with permission: "you may ask" is
+ * never "you lack permission." Both preambles open with the same marker
+ * so composition is idempotent (a composed prompt is never re-composed).
+ */
+
+/** The shared first line of both preambles - also the idempotence marker
+ * for composeEscalatedPrompt. */
+export const QUESTION_PREAMBLE_MARKER = "[hcn question protocol]";
+
+export const ESCALATION_PREAMBLE = `${QUESTION_PREAMBLE_MARKER}
+You are running headless: no one is watching this session live, but a caller relays answers between turns. This protocol never changes your permissions - asking is not how you obtain permission, and it never removes any permission this run already has. Use the tools you have exactly as granted.
+If and only if a genuine decision you cannot make defensibly blocks correct progress, ask by ending your turn: emit one fenced code block tagged hcn-question, as the last content of your final message, containing a single JSON object:
+
+\`\`\`hcn-question
+{"question": "<the decision you need made>", "options": ["<option 1>", "<option 2>"], "recommended": "<one of options>"}
+\`\`\`
+
+Say nothing after the block. Your turn ends there; the caller's user will answer, and your next turn continues from that answer. For every choice you can make defensibly yourself, do not ask - decide, act, and state the decision you made.`;
+
+export const NO_ESCALATION_PREAMBLE = `${QUESTION_PREAMBLE_MARKER}
+You are running headless and no one will answer you in this session. Never ask a question, never request input or confirmation, and never end your turn awaiting a reply. When a decision is ambiguous, pick the most defensible reading, state the assumption you proceeded under in one sentence, and continue to completion.`;
+
+/** Compose the transport preamble onto a prompt. Idempotent: a prompt
+ * that already carries either preamble (re-composition on resume, a
+ * caller that pre-composed) passes through unchanged. */
+export const composeEscalatedPrompt = (prompt: string, escalate: boolean): string =>
+  prompt.startsWith(QUESTION_PREAMBLE_MARKER)
+    ? prompt
+    : `${escalate ? ESCALATION_PREAMBLE : NO_ESCALATION_PREAMBLE}\n\n${prompt}`;
+
+/** The structured question a worker asks (the block's fields). */
+export interface QuestionBlock {
+  readonly question: string;
+  readonly options: readonly string[];
+  readonly recommended?: string;
+}
+
+/** Detection result: a parsed block, a named malformation (the worker
+ * tried to ask but botched the shape - surfaced, never swallowed), or
+ * null when no hcn-question block is present. */
+export type QuestionDetection = { readonly block: QuestionBlock } | { readonly malformed: string };
+
+/** One fenced-block candidate: the body text plus whether the fence was
+ * properly closed (an unclosed opener at end-of-text is still examined -
+ * the most likely formatting slip is forgetting the closing fence). */
+interface FenceCandidate {
+  readonly body: string;
+  readonly closed: boolean;
+}
+
+const FENCE_OPEN = /(?:^|\n)[ \t]*```[ \t]*hcn-question[ \t]*(?=\n)/g;
+
+/** All hcn-question fence bodies in a text, in order. */
+const fenceBodies = (text: string): FenceCandidate[] => {
+  const out: FenceCandidate[] = [];
+  FENCE_OPEN.lastIndex = 0;
+  for (let m = FENCE_OPEN.exec(text); m !== null; m = FENCE_OPEN.exec(text)) {
+    const bodyStart = m.index + m[0].length;
+    // The closing fence may be indented like the opener (probe evidence:
+    // indented blocks occur), so match newline + optional spaces + ```.
+    const close = text.slice(bodyStart).search(/\n[ \t]*```/);
+    if (close === -1) {
+      // Unclosed fence: the body runs to end-of-text. Only meaningful
+      // when nothing follows the opener - take it as a candidate anyway.
+      out.push({ body: text.slice(bodyStart), closed: false });
+      break;
+    }
+    const bodyEnd = bodyStart + close;
+    out.push({ body: text.slice(bodyStart, bodyEnd), closed: true });
+    FENCE_OPEN.lastIndex = bodyEnd;
+  }
+  return out;
+};
+
+const parseBlock = (body: string): QuestionDetection => {
+  let raw: unknown;
+  try {
+    raw = JSON.parse(body);
+  } catch (e) {
+    return { malformed: `hcn-question block is not valid JSON: ${(e as Error).message}` };
+  }
+  if (typeof raw !== "object" || raw === null || Array.isArray(raw)) {
+    return { malformed: "hcn-question block must be a JSON object" };
+  }
+  const obj = raw as Record<string, unknown>;
+  const { question, options, recommended } = obj;
+  if (typeof question !== "string" || question.trim() === "") {
+    return { malformed: 'hcn-question block field "question" must be a non-empty string' };
+  }
+  if (
+    !Array.isArray(options) ||
+    options.length === 0 ||
+    options.some((o) => typeof o !== "string" || o.trim() === "")
+  ) {
+    return {
+      malformed: 'hcn-question block field "options" must be an array of non-empty strings',
+    };
+  }
+  if (recommended !== undefined && typeof recommended !== "string") {
+    return { malformed: 'hcn-question block field "recommended" must be a string' };
+  }
+  return {
+    block: {
+      question,
+      options,
+      ...(recommended !== undefined ? { recommended } : {}),
+    },
+  };
+};
+
+/** Detect the hcn-question block in a message text. The LAST block wins
+ * (the protocol makes the block the turn's final content; a corrected
+ * re-emit supersedes an earlier one). An empty candidate body (a bare
+ * unclosed opener with nothing after it) is not a detection. */
+export const detectQuestionBlock = (text: string): QuestionDetection | null => {
+  const candidates = fenceBodies(text);
+  for (let i = candidates.length - 1; i >= 0; i--) {
+    const candidate = candidates[i];
+    if (candidate === undefined) continue;
+    if (candidate.body.trim() === "") continue;
+    return parseBlock(candidate.body);
+  }
+  return null;
+};