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

package/src/execution/failure.ts

@@ -14,12 +14,7 @@
  */
 
 import type { RefusalIssue } from "../interpretation/refusal.js";
-import type {
-  AuthFailureKind,
-  DiscoveryFacet,
-  LimitCode,
-  TurnOptionKey,
-} from "../knowledge/descriptor.js";
+import type { AuthFailureKind, DiscoveryFacet, LimitCode } from "../knowledge/descriptor.js";
 
 export const FAILURE_CLASSES = Object.freeze([
   "rate-limit",

package/src/execution/open-session.ts

@@ -14,7 +14,9 @@
  * sessionId + turnId correlation.
  */
 import { buildSessionArgv } from "../interpretation/argv.js";
+import { capabilitiesOf } from "../interpretation/capabilities.js";
 import { detectAuthFailureInLine, detectLimitInLine } from "../interpretation/limits.js";
+import { composeEscalatedPrompt, detectQuestionBlock } from "../interpretation/question.js";
 import {
   encodeSessionInput,
   resolveSessionInput,
@@ -52,6 +54,11 @@ export interface OpenSessionOptions {
   readonly model?: string;
   /** Working directory for the spawned harness. */
   readonly cwd?: string;
+  /** issue #44: question escalation in session mode (behavior
+   * instruction, default true). True composes the session preamble onto
+   * every send and arms block detection at turn end; false composes the
+   * no-ask instruction and disarms detection. */
+  readonly escalateQuestions?: boolean;
 }
 
 export class SessionClosedError extends Error {
@@ -124,6 +131,8 @@ export const openSession = (
 
   const turnsChannel = new AsyncChannel<AsyncIterable<HarnessEvent>>();
   const state = freshDecodeState(opts.sessionId);
+  const escalateQuestions = opts.escalateQuestions !== false;
+  const sessionInputMode = h.sessionMode;
   const stderrTail = new StderrTail();
   let turnCounter = 0;
   let activeTurn: AsyncChannel<HarnessEvent> | null = null;
@@ -137,6 +146,11 @@ export const openSession = (
   let resultError = false;
   let turnLimitSeen = false;
   let pumpError: unknown = null;
+  // issue #44: the active turn's last assistant message (where the
+  // hcn-question block lives) and whether the turn ended by asking.
+  let lastAssistantText: string | null = null;
+  let turnAsked = false;
+  let identityAnnounced = false;
 
   const safeSignal = (sig: "SIGTERM" | "SIGKILL"): void => {
     if (!dead) deps.signal(proc, sig);
@@ -148,7 +162,12 @@ export const openSession = (
 
   const writeUser = (text: string): boolean => {
     try {
-      stdin.write(encodeSessionInput(sessionInput, text));
+      stdin.write(
+        encodeSessionInput(
+          sessionInput,
+          composeEscalatedPrompt(text, escalateQuestions, "session"),
+        ),
+      );
       return true;
     } catch {
       activeTurn?.push({ kind: "error", message: "send failed: session stdin is gone" });
@@ -158,6 +177,8 @@ export const openSession = (
 
   const startTurn = (): void => {
     turnLimitSeen = false;
+    turnAsked = false;
+    lastAssistantText = null;
     activeTurn = new AsyncChannel<HarnessEvent>();
     activeTurnId = `${opts.sessionId}:turn-${++turnCounter}`;
     log({ event: "turn_start", sessionId: opts.sessionId, turnId: activeTurnId });
@@ -165,8 +186,44 @@ export const openSession = (
     turnsChannel.push(activeTurn);
   };
 
+  /** issue #44: at a turn boundary, scan the last assistant message for
+   * the hcn-question block - same structured-first discipline and
+   * last-message rule as streamTurn. The question event lands in the
+   * turn stream right before its done; a malformed block surfaces as an
+   * error event, never a silent no-op. */
+  const emitQuestionIfAsked = (): void => {
+    if (!escalateQuestions || lastAssistantText === null) return;
+    const detection = detectQuestionBlock(lastAssistantText);
+    if (detection === null) return;
+    if ("malformed" in detection) {
+      activeTurn?.push({ kind: "error", message: detection.malformed });
+      return;
+    }
+    turnAsked = true;
+    log({
+      event: "question",
+      sessionId: opts.sessionId,
+      turnId: activeTurnId,
+      harness: h.name,
+      options: detection.block.options.length,
+    });
+    activeTurn?.push({
+      kind: "question",
+      question: detection.block.question,
+      options: detection.block.options,
+      ...(detection.block.recommended !== undefined
+        ? { recommended: detection.block.recommended }
+        : {}),
+    });
+  };
+
   const endTurn = (done: HarnessEvent & { kind: "done" }): void => {
     if (activeTurn === null) return;
+    // Asking is a successful turn: the session semantic is "blocked on
+    // answer, session alive" - the done stays TURN-scoped (exitCode null
+    // in sessions) and the caller answers with the next send().
+    emitQuestionIfAsked();
+    if (turnAsked && done.cause === "clean") done = { ...done, cause: "awaiting-input" };
     activeTurn.push(done);
     activeTurn.close();
     log({
@@ -188,6 +245,9 @@ export const openSession = (
       state.limitSeen = true;
       turnLimitSeen = true;
     }
+    if (escalateQuestions && event.kind === "message" && event.role === "assistant") {
+      lastAssistantText = event.text;
+    }
     if (activeTurn !== null) {
       // Awaited by the pumps: past the channel's high water mark this
       // blocks the pump, so OS pipe backpressure reaches the child.
@@ -207,6 +267,28 @@ export const openSession = (
 
   const pumpStdout = async (): Promise<void> => {
     const lines = new LineBuffer();
+    const matches = (
+      record: Record<string, unknown>,
+      spec: Readonly<Record<string, string>>,
+    ): boolean => {
+      for (const [key, expected] of Object.entries(spec)) {
+        if (record[key] !== expected) return false;
+      }
+      return true;
+    };
+    // issue #44: pi rpc is identity-silent at startup; the probe round
+    // trip is the only way to read the id (spike fixtures). The response
+    // echoes our marker id, so it cannot be confused with a user-visible
+    // get_state response.
+    if (sessionInputMode?.identityProbe !== null && sessionInputMode !== null) {
+      try {
+        stdin.write(
+          `${JSON.stringify({ id: "hcn-identity", type: sessionInputMode.identityProbe.command })}\n`,
+        );
+      } catch {
+        // stdin already gone; the exited handler will surface the death.
+      }
+    }
     const handleLine = async (line: string): Promise<void> => {
       let parsed: Record<string, unknown> | null = null;
       try {
@@ -218,10 +300,70 @@ export const openSession = (
         }
         return;
       }
-      // The result line still feeds identity dedupe (claude includes
-      // session_id on it - a rotation announced there must not be missed).
+      // pi rpc bookkeeping: the probe response announces identity; a
+      // failed command response is a surfaced error, never a silent drop
+      // (spike: mid-stream prompts fail with success:false naming the
+      // remedy - hcn never sends those, but any other failure shows here).
+      if (parsed.type === "response") {
+        if (
+          parsed.id === "hcn-identity" &&
+          typeof parsed.command === "string" &&
+          parsed.command === sessionInputMode?.identityProbe?.command &&
+          parsed.success === true
+        ) {
+          const data = parsed.data as Record<string, unknown> | undefined;
+          const announced = data?.sessionId;
+          if (typeof announced !== "string") {
+            await routeEvent({
+              kind: "error",
+              message: "identity probe response carried no sessionId",
+            });
+          } else if (sessionInputMode.idFlag === null) {
+            // Harness-MINTED identity (pi rpc: `--session` refuses unknown
+            // ids, so fresh sessions omit the flag). The minted id IS the
+            // identity; opts.sessionId stays the caller-side handle.
+            if (!identityAnnounced) {
+              identityAnnounced = true;
+              state.lastSeenId = announced;
+              await routeEvent({
+                kind: "identity",
+                sessionId: announced,
+                authority: h.identity.authority,
+                capabilities: capabilitiesOf(h, opts.model ?? "", "headless-session"),
+              });
+            }
+          } else if (announced === opts.sessionId) {
+            if (!identityAnnounced) {
+              identityAnnounced = true;
+              await routeEvent({
+                kind: "identity",
+                sessionId: announced,
+                authority: h.identity.authority,
+                capabilities: capabilitiesOf(h, opts.model ?? "", "headless-session"),
+              });
+            }
+          } else {
+            await routeEvent({
+              kind: "error",
+              message: `identity rotated: session announced ${JSON.stringify(announced)} but ${opts.sessionId} was requested`,
+            });
+          }
+          return;
+        }
+        if (parsed.success === false) {
+          await routeEvent({
+            kind: "error",
+            message: `rpc command failed: ${JSON.stringify(parsed.command)} - ${JSON.stringify(parsed.error ?? "unknown error")}`,
+          });
+        }
+        return;
+      }
+      // The turn-end record still feeds identity dedupe (claude includes
+      // session_id on result - a rotation announced there must not be
+      // missed).
       const events = decodeParsed(h, parsed, state, opts.model ?? "");
-      if (parsed.type === "result") {
+      const isTurnEnd = sessionInputMode !== null && matches(parsed, sessionInputMode.turnEnd);
+      if (isTurnEnd) {
         // decodeParsed already surfaces the is_error case as an error event
         // (content.ts claude reader); routing the events is enough - we only
         // still track resultError here to classify the done cause.

package/src/interpretation/argv.ts

@@ -164,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);
@@ -172,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

@@ -33,13 +33,34 @@ Say nothing after the block. Your turn ends there; the caller's user will answer
 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 =>
+/** 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
-    : `${escalate ? ESCALATION_PREAMBLE : NO_ESCALATION_PREAMBLE}\n\n${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 {

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" } },