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

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;
 }
@@ -159,7 +164,7 @@ export const buildSessionArgv = (h: HarnessDescriptor, opts: SessionOptions): st
     throw new ArgvRefusalError({
       issue: "no-session-mode",
       harness: h.name,
-      supported: ["session is claude-only"],
+      supported: ["session is available where sessionMode is declared"],
     });
   }
   assertUsableSessionId(opts.sessionId);
@@ -167,8 +172,9 @@ export const buildSessionArgv = (h: HarnessDescriptor, opts: SessionOptions): st
     h.bin,
     ...h.launch.baseFlags,
     ...h.sessionMode.flags,
-    h.sessionMode.idFlag,
-    opts.sessionId,
+    // idFlag null = the harness refuses unknown ids and mints its own
+    // (pi rpc); the caller-side sessionId stays a correlation handle.
+    ...(h.sessionMode.idFlag !== null ? [h.sessionMode.idFlag, opts.sessionId] : []),
   ];
   if (opts.model !== undefined) {
     const validated = validateModel(h, opts.model);

package/src/interpretation/presence.ts

@@ -18,7 +18,9 @@ export interface ProcessRow {
 const idBearingFlags = (h: HarnessDescriptor): readonly string[] => [
   h.resume.flag,
   ...h.resume.aliases,
-  ...(h.sessionMode === null ? [] : [h.sessionMode.idFlag]),
+  // idFlag null = the harness mints session ids and accepts no id flag
+  // (pi rpc); such processes never carry a caller id to match anyway.
+  ...(h.sessionMode === null || h.sessionMode.idFlag === null ? [] : [h.sessionMode.idFlag]),
   // muse's interactive process IS `muse resume <id>` - the parse-only
   // spelling is exactly what a live interactive argv looks like.
   ...(h.resume.positionalParseWord === undefined ? [] : [h.resume.positionalParseWord]),

package/src/interpretation/question.ts

@@ -0,0 +1,158 @@
+/**
+ * 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.`;
+
+/** Session-mode variant (issue #44): the worker lives in ONE persistent
+ * session with a live stdin - the ask stops generation but the session
+ * stays open, and the answer arrives as the next user message on the
+ * same session. No exit, no resume. */
+export const SESSION_ESCALATION_PREAMBLE = `${QUESTION_PREAMBLE_MARKER}
+You are running in a persistent session: no one is watching live, but the caller relays answers back into this same session. 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 stopping: emit one fenced code block tagged hcn-question, as the last content of your reply, 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 and stop generating. The caller's user will answer, and the answer arrives as the next user message in this session - continue from it. For every choice you can make defensibly yourself, do not ask - decide, act, and state the decision you made.`;
+
+/** Compose the transport preamble onto a prompt. `mode` selects the
+ * contract wording: "turn" (exit-and-resume transport, hcn run) or
+ * "session" (live channel, hcn session). Idempotent: a prompt that
+ * already carries any preamble passes through unchanged - a turn-mode
+ * preamble is never re-composed into a session one (the marker matches
+ * both; the already-composed contract stands). */
+export const composeEscalatedPrompt = (
+  prompt: string,
+  escalate: boolean,
+  mode: "turn" | "session" = "turn",
+): string =>
+  prompt.startsWith(QUESTION_PREAMBLE_MARKER)
+    ? prompt
+    : `${mode === "session" && escalate ? SESSION_ESCALATION_PREAMBLE : 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;
+};

package/src/interpretation/session-input.ts

@@ -41,5 +41,10 @@ export const encodeSessionInput = (input: SessionInputContract, text: string): s
         type: "user",
         message: { role: "user", content: [{ type: "text", text }] },
       })}\n`;
+    case "pi-rpc-prompt":
+      // Verified against pi 0.84.2 rpc (spike fixtures): a prompt command
+      // while idle; hcn never writes mid-run (it queues sends itself), so
+      // no streamingBehavior field is ever needed.
+      return `${JSON.stringify({ id: "hcn-send", type: "prompt", message: text })}\n`;
   }
 };

package/src/knowledge/claude-code.ts

@@ -61,6 +61,8 @@ export const claudeCode: HarnessDescriptor = deepFreeze({
     ],
     idFlag: "--session-id",
     input: { kind: "claude-sdk-user-message" },
+    turnEnd: { type: "result" },
+    identityProbe: null,
   },
   output: {
     // --output-format/--include-partial-messages only work with --print, so

package/src/knowledge/descriptor.ts

@@ -30,7 +30,7 @@ export type StreamingGranularity = "token" | "message" | "none";
 
 export type HarnessMode = "headless-turn" | "headless-session" | "interactive";
 
-export const SESSION_INPUT_KINDS = ["claude-sdk-user-message"] as const;
+export const SESSION_INPUT_KINDS = ["claude-sdk-user-message", "pi-rpc-prompt"] as const;
 export type SessionInputKind = (typeof SESSION_INPUT_KINDS)[number];
 
 export interface SessionInputContract {
@@ -241,11 +241,22 @@ export interface HarnessDescriptor {
   };
   /** Persistent headless session support: the exact flag set that opens one
    * lucid-owned process serving many turns, or null when the harness has no
-   * such mode. `idFlag` pins the caller-assigned session identity. */
+   * such mode. `idFlag` pins the caller-assigned session identity.
+   * `turnEnd` is the stdout record that delimits one turn (claude: the
+   * `result` record; pi rpc: `agent_settled`). `identityProbe`, when
+   * present, names a command the runner writes at spawn whose response
+   * carries the session id - pi rpc is identity-silent at startup (spike
+   * evidence: test/fixtures/pi-rpc-spike), so identity needs a round trip. */
   readonly sessionMode: {
     readonly flags: readonly string[];
-    readonly idFlag: string;
+    /** Pin an EXISTING session id; null when the harness only accepts
+     * caller ids that already exist (pi rpc: `--session` refuses unknown
+     * ids - spike evidence), so fresh sessions omit the flag and the
+     * harness mints the id, readable via `identityProbe`. */
+    readonly idFlag: string | null;
     readonly input: SessionInputContract;
+    readonly turnEnd: Readonly<Record<string, string>>;
+    readonly identityProbe: { readonly command: string } | null;
   } | null;
   /** Streaming is a property of the INVOCATION, not the harness: each pin
    * names the flag set that unlocks a granularity, checked in order, first

package/src/knowledge/pi.ts

@@ -37,11 +37,23 @@ export const piCli: HarnessDescriptor = deepFreeze({
     onMissing: "create",
     extraFlags: ["-p", "--mode", "json"],
   },
-  // --mode rpc exists on 0.84.2 but its session semantics are unverified
-  // against a live run; per the truthfulness rule it stays null until a
-  // spike proves the contract (the claude slice is the proven vertical -
-  // D-003).
-  sessionMode: null,
+  // --mode rpc exists on 0.84.2 and its session semantics are now VERIFIED
+  // against a live run (2026-08-19 spike, evidence at
+  // test/fixtures/pi-rpc-spike): JSONL both directions, agent_settled
+  // delimits turns, steer/follow_up queue mid-run (hcn never needs them -
+  // it queues sends itself), identity is silent at startup and readable
+  // only via a get_state round trip, stdin EOF exits rc=0. The claude
+  // slice remains the proven vertical (D-003); this entry is the second.
+  sessionMode: {
+    flags: ["--mode", "rpc"],
+    // `--session <id>` requires an EXISTING id ("No session found" on a
+    // fresh uuid - live-verified); fresh sessions omit it and pi mints
+    // the id, readable only through the get_state probe.
+    idFlag: null,
+    input: { kind: "pi-rpc-prompt" },
+    turnEnd: { type: "agent_settled" },
+    identityProbe: { command: "get_state" },
+  },
   output: {
     // pi -p prints plain text; --mode json emits structured v3 records
     // INCLUDING assistantMessageEvent text_delta tokens (verified 0.84.2),
@@ -88,10 +100,12 @@ export const piCli: HarnessDescriptor = deepFreeze({
     images: false,
     streamingByMode: {
       "headless-turn": "token",
-      "headless-session": "none",
+      // rpc mode streams the same assistantMessageEvent deltas json mode
+      // does (spike fixture 02: text/thinking deltas under message_update).
+      "headless-session": "token",
       interactive: "none",
     },
-    session: false,
+    session: true,
   },
   turnOptions: {
     effort: { kind: "effort", render: { kind: "flag-value", flag: "--thinking" } },