@dungle-scrubs/harness-cli-normalizer 0.5.4 → 0.5.6

package/src/cli/config.ts

@@ -76,9 +76,8 @@ const KNOWN_KEYS = new Set([
   "maxSteps",
   "toolsets",
   "timeout",
-  // issue #41: question escalation (behavior instruction, not a turn
-  // option - it rides the prompt preamble, never a harness flag).
-  "escalateQuestions",
+  // question mode: ask|assume|none (behavior instruction, not a turn option)
+  "questions",
   // issue #48: payload-stripping dimensions (opt-in-only, no profile
   // entry by ratification).
   "systemPrompt",
@@ -88,7 +87,8 @@ const KNOWN_KEYS = new Set([
 ]);
 
 const LIST_KEYS = new Set(["tools", "excludeTools"]);
-const BOOL_KEYS = new Set(["autonomy", "write", "shell", "escalateQuestions"]);
+const BOOL_KEYS = new Set(["autonomy", "write", "shell"]);
+const QUESTIONS_VALUES = new Set(["ask", "assume", "none"]);
 
 /** Parse + validate config text. Throws ConfigError with the offending key
  * named on any violation - never warns and continues. */
@@ -227,6 +227,15 @@ export const parseUserConfig = (text: string): Partial<TurnOptions> => {
       (out as Record<string, unknown>)[key] = value;
       continue;
     }
+    if (key === "questions") {
+      if (typeof value !== "string" || !QUESTIONS_VALUES.has(value)) {
+        throw new ConfigError(
+          `config key ${JSON.stringify(key)} must be one of ${[...QUESTIONS_VALUES].join(", ")}`,
+        );
+      }
+      (out as Record<string, unknown>).questions = value;
+      continue;
+    }
     if (BOOL_KEYS.has(key)) {
       if (typeof value !== "boolean") {
         throw new ConfigError(`config key ${JSON.stringify(key)} must be a boolean`);

package/src/cli/help.ts

@@ -48,12 +48,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
+  --questions <ask|assume|none>
+                            Which preamble to inject: ask = escalation
+                            protocol (DEFAULT, question event +
+                            done cause "awaiting-input", exit 0), assume =
+                            never ask, state assumption, none = inject
+                            nothing
   --system-prompt <text>    Replace the built-in system prompt (claude, pi:
                             flag; codex: -c instructions=<text-or-path>;
                             muse refuses. claude pairs the dynamic-section
@@ -78,12 +78,15 @@ 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). The answer path for
-                            question escalation: resume with the chosen
-                            answer as the prompt; id continuity per
+  --resume <uuid>           Resume session id (UUID). Continues the
+                            conversation where it left off. 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)
-                            Note: pi and muse create a new session when the id is unknown - verify it exists
+                            Note: hcn refuses an unknown id before spawn
+                            (exit 2) for harnesses that would otherwise
+                            create a fresh session silently (pi, muse)
   --session-id <uuid>       Alias for --resume (mutually exclusive with --resume)
   --                        Passthrough: native harness args verbatim
                             (failures surface as labeled native errors)
@@ -102,9 +105,8 @@ Defaults with no flags:
   profile). toolMap is config-only (no flag) - canonical -> native
   mapping per harness. A bare pi run renders no --tools list: pi's list
   is a strict allowlist and would drop extension and MCP tools; name
-  them through toolMap or native:<name> when you grant. Question
-  escalation defaults ON (config key
-  "escalateQuestions"; it is a prompt preamble, never a harness flag).
+  them through toolMap or native:<name> when you grant. Question mode defaults to ask (config keys
+  "questions"; 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.
 `;
@@ -120,8 +122,9 @@ Options:
   --json                    Machine surface: NDJSON events on stdout, NDJSON
                             commands on stdin ({"op":"send","id":..,"text":..},
                             "answer", "close"). Every send is answered with one
-                            disposition (started | queued | rejected); a queued
-                            send's id rides to the turn that consumes it. The
+                            disposition (started | rejected); every send is
+                            handed to the harness, and the turn that consumes it
+                            carries its id. The
                             stream opens with a session event and ends with a
                             closed event. Exit 0 clean, 1 otherwise, 2 refusal.
   --stall <seconds>         Per-turn inactivity budget; the turn ends and the
@@ -129,12 +132,18 @@ Options:
                             (default: no limit)
   --provider <value>        Provider (pi only)
   --model <id>              Model for the session
-  --session-id <uuid>       Session id (UUID, else random; re-enters an
-                            existing session)
-  --escalate-questions      Worker may ask; question renders as a pickable
-                            menu, the answer flows back into the SAME live
-                            session (DEFAULT)
-  --no-escalate-questions   Worker never asks; states its assumption
+  --resume <uuid>           Resume session id (UUID). Continues the
+                            conversation where it left off. --session-id
+                            is an alias (mutually exclusive with --resume).
+                            If no id is given, a fresh session is started
+                            with a new id. hcn refuses an unknown id before
+                            spawn (exit 2) for harnesses that would otherwise
+                            create a fresh session silently (pi)
+  --session-id <uuid>       Alias for --resume (mutually exclusive with --resume)
+  --questions <ask|assume|none>
+                            Which preamble to inject: ask = worker may
+                            ask (DEFAULT, pickable menu), assume = never
+                            ask, none = inject nothing
   --cwd <path>              Working directory
   --help                    Show help
   --version                 Show version
@@ -167,11 +176,11 @@ Options:
   --autonomy / --no-autonomy
   --write / --no-write
   --shell / --no-shell
-  --escalate-questions / --no-escalate-questions
+  --questions <ask|assume|none>
                             (accepted; renders nothing - rides the run prompt)
   --max-steps <n>
   --no-tools, --no-instruction-files, --no-extensions, --no-skills
-  --escalate-questions / --no-escalate-questions
+  --questions <ask|assume|none>
                             Accepted; renders nothing in argv (the mode
                             rides the run prompt, not a harness flag)
   --cwd <path>

package/src/cli/inspect.ts

@@ -210,13 +210,16 @@ export const inspect = async (harnessName: string, rawArgs: string[]): Promise<v
     try {
       const { resolveSkillNames, listKnownSkills } = await import("./skills-root.js");
       const resolvedSkills = resolveSkillNames(rawSkills, h.name);
-      const claudeTokens: string[] = [];
+      const skillTokens: string[] = [];
       if (h.name === "claude") {
         const { claudeSkillOverridesArg } = await import("../interpretation/skills-selection.js");
-        claudeTokens.push(...claudeSkillOverridesArg(listKnownSkills(), resolvedSkills));
+        skillTokens.push(...claudeSkillOverridesArg(listKnownSkills(), resolvedSkills));
+      } else if (h.name === "codex") {
+        const { codexSkillConfigArg } = await import("../interpretation/skills-selection.js");
+        skillTokens.push(...codexSkillConfigArg(listKnownSkills(), resolvedSkills));
       }
       (turnOpts as unknown as Record<string, unknown>).skills = resolvedSkills;
-      (turnOpts as unknown as Record<string, unknown>).__claudeSkillTokens = claudeTokens;
+      (turnOpts as unknown as Record<string, unknown>).__skillTokens = skillTokens;
     } catch (err) {
       if (err instanceof ArgvRefusalError) {
         process.stderr.write(`${err.message}\n`);
@@ -301,9 +304,8 @@ export const inspect = async (harnessName: string, rawArgs: string[]): Promise<v
   let argv: string[];
   try {
     argv = buildLaunchArgv(h, fullOpts);
-    const claudeTokens = (effectiveRest as unknown as { __claudeSkillTokens?: string[] })
-      .__claudeSkillTokens;
-    if (claudeTokens !== undefined && claudeTokens.length > 0) argv.push(...claudeTokens);
+    const skillTokens = (effectiveRest as unknown as { __skillTokens?: string[] }).__skillTokens;
+    if (skillTokens !== undefined && skillTokens.length > 0) argv.push(...skillTokens);
   } catch (err) {
     if (err instanceof ArgvRefusalError) {
       refuse(refusalOf(err as ArgvRefusalError), false);

package/src/cli/render.ts

@@ -81,6 +81,23 @@ export const renderEvent = (event: HarnessEvent, state: RenderState): void => {
   }
 };
 
-export const writeEventNdjson = (event: HarnessEvent): void => {
+/** Write one NDJSON event, reporting whether stdout took it immediately.
+ *
+ * `false` means the kernel buffer is full and the bytes are queued in the
+ * process. A caller streaming a turn MUST wait for `drain` before writing
+ * again (see `writeEventNdjsonAsync`); a caller writing one terminal pair on
+ * the way out may ignore it, because Node flushes pending stdout writes
+ * before it exits. */
+export const writeEventNdjson = (event: HarnessEvent): boolean =>
   process.stdout.write(`${JSON.stringify(event)}\n`);
+
+/** The streaming form: resolves once stdout has taken the line.
+ *
+ * Without this a slow reader is absorbed by the process rather than pushed
+ * back on: hcn keeps pulling from the harness and buffering, so memory grows
+ * with the turn instead of the harness being stalled. RFC-01 rule 8 names
+ * both hops; this is the hcn-to-consumer one. */
+export const writeEventNdjsonAsync = async (event: HarnessEvent): Promise<void> => {
+  if (writeEventNdjson(event)) return;
+  await new Promise<void>((resolve) => process.stdout.once("drain", resolve));
 };

package/src/cli/resume-guard.ts

@@ -1,4 +1,4 @@
-import { existsSync, realpathSync } from "node:fs";
+import { existsSync, readdirSync, realpathSync, statSync } from "node:fs";
 import { storePath } from "../interpretation/store.js";
 import type { HarnessDescriptor } from "../knowledge/descriptor.js";
 
@@ -31,5 +31,29 @@ export const resumeStore = (
   } catch {
     path = null;
   }
-  return { path, exists: path !== null && existsSync(path) };
+  return { path, exists: path !== null && sessionExistsAt(path, opts.sessionId) };
+};
+
+/** A store template that resolves to a FILE names the session directly and
+ * existence is the file's. One that resolves to a DIRECTORY names where the
+ * harness files every session for this cwd, and the session is one entry in
+ * it whose name carries the id somewhere - pi writes `<timestamp>_<id>.jsonl`,
+ * so the id's position is not a template. Checking only that the directory
+ * exists reported every id as present once any session had ever run in the
+ * cwd, which made the guard pass unknown ids on pi and, once `origin` rode
+ * on it, reported a brand-new session as resumed. */
+const sessionExistsAt = (path: string, sessionId: string): boolean => {
+  if (!existsSync(path)) return false;
+  let isDir = false;
+  try {
+    isDir = statSync(path).isDirectory();
+  } catch {
+    return false;
+  }
+  if (!isDir) return true;
+  try {
+    return readdirSync(path).some((name) => name.includes(sessionId));
+  } catch {
+    return false;
+  }
 };

package/src/cli/run.ts

@@ -9,7 +9,7 @@ import { recognizeNativeSpelling, supportedBy } from "../interpretation/support.
 import { defaultDescriptors } from "../knowledge/overrides.js";
 import { parseRunExtra, parseTurnOptions, resolvePromptAsync } from "./args.js";
 import { refusalOf, refuse } from "./refuse.js";
-import { createRenderState, renderEvent, writeEventNdjson } from "./render.js";
+import { createRenderState, renderEvent, writeEventNdjsonAsync } from "./render.js";
 import { resolveHarness } from "./resolve-harness.js";
 import { resumeStore } from "./resume-guard.js";
 
@@ -185,13 +185,16 @@ export const run = async (harnessName: string, rawArgs: string[]): Promise<void>
     try {
       const { resolveSkillNames, listKnownSkills } = await import("./skills-root.js");
       const resolvedSkills = resolveSkillNames(rawSkills, h.name);
-      const claudeTokens: string[] = [];
+      const skillTokens: string[] = [];
       if (h.name === "claude") {
         const { claudeSkillOverridesArg } = await import("../interpretation/skills-selection.js");
-        claudeTokens.push(...claudeSkillOverridesArg(listKnownSkills(), resolvedSkills));
+        skillTokens.push(...claudeSkillOverridesArg(listKnownSkills(), resolvedSkills));
+      } else if (h.name === "codex") {
+        const { codexSkillConfigArg } = await import("../interpretation/skills-selection.js");
+        skillTokens.push(...codexSkillConfigArg(listKnownSkills(), resolvedSkills));
       }
       (turnOpts as unknown as Record<string, unknown>).skills = resolvedSkills;
-      (turnOpts as unknown as Record<string, unknown>).__claudeSkillTokens = claudeTokens;
+      (turnOpts as unknown as Record<string, unknown>).__skillTokens = skillTokens;
     } catch (err) {
       if (err instanceof ArgvRefusalError) {
         refuse(refusalOf(err), wantJson);
@@ -209,9 +212,9 @@ export const run = async (harnessName: string, rawArgs: string[]): Promise<void>
     project?: Partial<ReturnType<typeof parseTurnOptions>>;
   } = {};
   // Config files load on EVERY run, launch or resume: the tiers feed the
-  // defaults profile on launch, and issue #41's escalateQuestions (a
+  // defaults profile on launch, and issue #41's questions (a
   // behavior instruction, not a turn option) resolves from them on resume
-  // too - otherwise a no-escalate session would flip its preamble on the
+  // too - otherwise a no-ask session would flip its preamble on the
   // answer turn. Resolution of TURN options stays launch-only.
   const tiers = resolvedTiers;
   {
@@ -256,39 +259,34 @@ export const run = async (harnessName: string, rawArgs: string[]): Promise<void>
     writeProvenance(h.name, provenance, unrenderable);
   }
 
-  // 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
+  // question mode precedence arg > project > user > default (ask)
+  const projectQuestions = (resolvedTiers.project as { questions?: string } | undefined)?.questions;
+  const userQuestions = (resolvedTiers.user as { questions?: string } | undefined)?.questions;
+  const rawMode = (turnOpts as { questions?: string }).questions;
+  const questionMode =
+    rawMode !== undefined
+      ? (rawMode as import("../interpretation/question.js").QuestionMode)
+      : projectQuestions !== undefined
+        ? (projectQuestions as import("../interpretation/question.js").QuestionMode)
+        : userQuestions !== undefined
+          ? (userQuestions as import("../interpretation/question.js").QuestionMode)
+          : ("ask" as const);
+  const questionTier =
+    rawMode !== undefined
       ? "arg"
-      : projectEscalate !== undefined
+      : projectQuestions !== undefined
         ? "project-config"
-        : userEscalate !== undefined
+        : userQuestions !== undefined
           ? "user-config"
           : "default";
 
   const fullOpts = {
     ...effectiveTurnOpts,
-    prompt: composeEscalatedPrompt(prompt, escalateQuestions),
+    prompt: composeEscalatedPrompt(prompt, questionMode),
     cwd: extra.cwd,
     env: extra.env,
     resume: extra.resume,
-    escalateQuestions,
+    questions: questionMode,
     ...(passthrough.length > 0 ? { passthrough } : {}),
     ...(isExplicit ? { __explicitPrompt: true as const } : {}),
   } as Parameters<typeof streamTurn>[1] & {
@@ -304,7 +302,7 @@ export const run = async (harnessName: string, rawArgs: string[]): Promise<void>
     if (fullOpts.resume) {
       // 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.
+      // (questions preamble, timeout budget) still applies.
       preArgv = buildResumeArgv(h, {
         ...(turnOpts as object),
         prompt: fullOpts.prompt,
@@ -321,10 +319,10 @@ export const run = async (harnessName: string, rawArgs: string[]): Promise<void>
         prompt: fullOpts.prompt,
         __explicitPrompt: isExplicit,
       } as never);
-      const claudeSkillTokens = (effectiveTurnOpts as unknown as { __claudeSkillTokens?: string[] })
-        .__claudeSkillTokens;
-      if (claudeSkillTokens !== undefined && claudeSkillTokens.length > 0) {
-        preArgv.push(...claudeSkillTokens);
+      const skillTokens = (effectiveTurnOpts as unknown as { __skillTokens?: string[] })
+        .__skillTokens;
+      if (skillTokens !== undefined && skillTokens.length > 0) {
+        preArgv.push(...skillTokens);
       }
     }
     _validated = true;
@@ -349,9 +347,7 @@ export const run = async (harnessName: string, rawArgs: string[]): Promise<void>
     }
     // 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`,
-    );
+    process.stderr.write(`provenance: questions = ${questionMode} (${questionTier})\n`);
     // On a harness whose include flag is not a strict allowlist (claude),
     // a name outside the curated set passes through ungated; say which
     // ones so a wrong-case name is visible. A grant with no known name at
@@ -465,7 +461,9 @@ export const run = async (harnessName: string, rawArgs: string[]): Promise<void>
     for await (const event of events) {
       lastEvent = event;
       if (wantJson) {
-        writeEventNdjson(event);
+        // Await the write: a consumer that stops reading must stall the
+        // harness, not be absorbed into this process's memory.
+        await writeEventNdjsonAsync(event);
       } else {
         renderEvent(event, state);
       }

package/src/cli/session-json.ts

@@ -4,7 +4,7 @@
  * with the control events (`session`, `turn`, `disposition`, `closed`) that
  * a program needs to drive a session it does not own the timing of. RFC-01.
  *
- * This owns the wire framing only. The turn lifecycle, the queue, and the id
+ * This owns the wire framing only. The turn lifecycle and the id
  * correlation live in `openSession`; this reads the id off the yielded turn
  * rather than shadowing the runner's delivery order.
  */
@@ -16,6 +16,7 @@ import {
   type SessionHandle,
   type SessionSendResult,
 } from "../execution/open-session.js";
+import type { QuestionMode } from "../interpretation/question.js";
 
 /** What the CLI reads back after a close, captured from the runner's
  * `session_close` boundary log. */
@@ -24,15 +25,18 @@ export interface CloseInfo {
   cause: string;
 }
 
+export type SessionOrigin = "fresh" | "resumed";
+
 export interface JsonSessionArgs {
   readonly handle: SessionHandle;
   readonly sessionId: string;
   readonly harness: string;
   readonly hcnVersion: string;
-  readonly escalateQuestions: boolean;
+  readonly questions?: QuestionMode;
+  readonly origin: SessionOrigin;
   /** Read after close - the runner's final exitCode and cause. */
   readonly getCloseInfo: () => CloseInfo;
-  /** Read after close - ids the runner accepted as queued and never
+  /** Read after close - ids the runner accepted and never
    * delivered. Each owes the consumer a rejection (RFC S003). */
   readonly getDroppedIds?: () => readonly string[];
   /** Injected for tests; defaults to process.stdin / process.stdout. */
@@ -116,12 +120,14 @@ export const runJsonSession = async (a: JsonSessionArgs): Promise<number> => {
     return chain;
   };
 
+  const qMode: QuestionMode = a.questions ?? "ask";
   await emit({
     kind: "session",
     sessionId: a.sessionId,
     harness: a.harness,
     hcn: a.hcnVersion,
-    escalateQuestions: a.escalateQuestions,
+    questions: qMode,
+    origin: a.origin,
   });
 
   // Shared between the pumps: the last question asked, whether the last turn
@@ -154,6 +160,17 @@ export const runJsonSession = async (a: JsonSessionArgs): Promise<number> => {
   })();
 
   const rl = createInterface({ input: a.input ?? process.stdin });
+  // Ids accepted from stdin but not yet answered with a disposition. If the
+  // command stream itself fails, each is owed one: silence would leave the
+  // consumer waiting on an answer that can no longer arrive.
+  const unanswered = new Set<string>();
+  let stdinError: string | null = null;
+  const commandStream = (a.input ?? process.stdin) as {
+    on?: (event: string, listener: (err: NodeJS.ErrnoException) => void) => unknown;
+  };
+  commandStream.on?.("error", (err) => {
+    stdinError = err.code ?? err.message;
+  });
   const stdinPump = (async () => {
     for await (const line of rl) {
       if (line.trim() === "") continue;
@@ -177,12 +194,14 @@ export const runJsonSession = async (a: JsonSessionArgs): Promise<number> => {
         text = composeAnswer(lastQuestion, cmd.text);
       }
       let sent: SessionSendResult;
+      unanswered.add(cmd.id);
       try {
         sent = a.handle.send({ id: cmd.id, text });
       } catch (err) {
         // A session the caller already closed, or one already dead: a
         // different remedy from a broken pipe, so a different reason.
         if (err instanceof SessionClosedError) {
+          unanswered.delete(cmd.id);
           await emit({
             kind: "disposition",
             id: cmd.id,
@@ -191,8 +210,10 @@ export const runJsonSession = async (a: JsonSessionArgs): Promise<number> => {
           });
           continue;
         }
+        unanswered.delete(cmd.id);
         throw err;
       }
+      unanswered.delete(cmd.id);
       await emit({
         kind: "disposition",
         id: cmd.id,
@@ -201,16 +222,33 @@ export const runJsonSession = async (a: JsonSessionArgs): Promise<number> => {
       });
     }
   })();
+  // A command stream that breaks is not a clean end of input, but it is also
+  // not a crash of this process: record it and close the session in order.
+  // The caught form is what the race waits on - the raw pump would reject
+  // straight out of runJsonSession.
+  const stdinDone = stdinPump.catch((err: unknown) => {
+    stdinError = err instanceof Error ? err.message : String(err);
+  });
 
   // Whichever ends first drives the close: a close/EOF from stdin, or the
   // session dying (the turns iterable ends). close() is idempotent; closing
   // the readline unblocks the stdin pump if the session died first.
-  await Promise.race([stdinPump, stdoutPump]);
+  await Promise.race([stdinDone, stdoutPump]);
   await a.handle.close();
   rl.close();
-  await Promise.allSettled([stdinPump, stdoutPump]);
+  await Promise.allSettled([stdinDone, stdoutPump]);
+
+  // A broken command stream is a fact the consumer needs, and every send it
+  // swallowed is owed its answer.
+  if (stdinError !== null) {
+    await emit({ kind: "error", message: `command stream failed: ${stdinError}` });
+  }
+  for (const id of unanswered) {
+    await emit({ kind: "disposition", id, disposition: "rejected", reason: "closed" });
+  }
+  unanswered.clear();
 
-  // Every input the runner accepted as queued and then lost gets its own
+  // Every input the runner accepted and then lost gets its own
   // rejection, before the terminal line (RFC S003).
   for (const id of a.getDroppedIds?.() ?? []) {
     await emit({ kind: "disposition", id, disposition: "rejected", reason: "closed" });