@dungle-scrubs/harness-cli-normalizer 0.6.0 → 0.6.2

package/src/interpretation/argv.ts

@@ -4,24 +4,47 @@
  * prompt before tool grants) and the spawn-boundary refusals live here so
  * no caller re-derives them.
  */
-import type { HarnessDescriptor, StreamingGranularity } from "../knowledge/descriptor.js";
+import type {
+  AccessValue,
+  HarnessDescriptor,
+  StreamingGranularity,
+} from "../knowledge/descriptor.js";
 import { defaultDescriptors } from "../knowledge/overrides.js";
+import { assertIsolationCombination } from "./isolation.js";
 import { ArgvRefusalError } from "./refusal.js";
 import { assertUsableSessionId, SESSION_ID_MAX, SessionIdRefusalError } from "./session-id.js";
-import { renderSkillsSelection } from "./skills-selection.js";
+import { renderSkillsSelection, type SkillsSelection } from "./skills-selection.js";
 import { supportedBy } from "./support.js";
 import { renderToolSelection } from "./tool-selection.js";
+import type { ToolMap } from "./tool-vocabulary.js";
 import { renderTurnOptions } from "./turn-options.js";
 import { validateModel } from "./vocabulary.js";
 
 export type { RefusalIssue } from "./refusal.js";
 export { ArgvRefusalError, buildRefusalMessage, REFUSAL_ISSUES } from "./refusal.js";
 
-/** One guard for every builder that places a positional prompt. Selector
+/** A prompt carries its own provenance (RFC-02 change 13): a plain string
+ * is an implicit, positional prompt; the object form came from an explicit
+ * flag or file, so a leading dash is the caller's intent, not a flag. */
+export type Prompt = string | { readonly text: string; readonly explicit: boolean };
+
+/** The one accessor for the prompt's text, for builders, the runner, and
+ * redaction alike. */
+export const promptTextOf = (opts: { readonly prompt: Prompt }): string =>
+  typeof opts.prompt === "string" ? opts.prompt : opts.prompt.text;
+
+/** The same prompt with new text: the composed form keeps its provenance. */
+export const withPromptText = (prompt: Prompt, text: string): Prompt =>
+  typeof prompt === "string" ? text : { ...prompt, text };
+
+/** One guard for every builder that places a positional prompt: an
+ * implicit prompt may not start with '-' (it would be parsed as a flag),
+ * while an explicit one - `hcn run --prompt "-bad"` - passes. Selector
  * hygiene (session ids) lives in session-id.ts; model selectors go through
  * validateModel - both refuse, never sanitize. */
-const assertCleanPrompt = (h: HarnessDescriptor, prompt: string): void => {
-  if (prompt.startsWith("-")) {
+const assertCleanPrompt = (h: HarnessDescriptor, prompt: Prompt): void => {
+  if (typeof prompt !== "string" && prompt.explicit) return;
+  if (promptTextOf({ prompt }).startsWith("-")) {
     throw new ArgvRefusalError({
       issue: "prompt-flag-injection",
       harness: h.name,
@@ -31,19 +54,6 @@ const assertCleanPrompt = (h: HarnessDescriptor, prompt: string): void => {
   }
 };
 
-/**
- * Variant that allows a leading '-' when the caller explicitly opted in via
- * --prompt / --prompt-file. The positional guard still applies for implicit
- * positional prompts, but an explicit opt-in bypasses it so `hcn run --prompt "-bad"`
- * succeeds while `hcn run "-bad"` refuses. The caller must set
- * `__explicitPrompt: true` on the options object when the prompt came from an
- * explicit flag.
- */
-const assertCleanPromptMaybe = (h: HarnessDescriptor, prompt: string, explicit?: boolean): void => {
-  if (explicit) return;
-  assertCleanPrompt(h, prompt);
-};
-
 export interface DiscoveryOptions {
   readonly tools?: boolean;
   readonly instructionFiles?: boolean;
@@ -52,18 +62,20 @@ export interface DiscoveryOptions {
 }
 
 export interface TurnOptions {
-  readonly prompt: string;
+  readonly isolation?: "tool-free";
+  readonly prompt: Prompt;
   readonly tools?: readonly string[];
   readonly excludeTools?: readonly string[];
-  /** Caller-directed skills allowlist: resolved absolute paths, one per
-   * skill. Rendering: pi loads each via --skill with discovery off;
-   * claude turns off the complement via skillOverrides settings; codex
-   * and muse refuse (structural - no per-skill surface). */
-  readonly skills?: readonly string[];
+  /** Caller-directed skills allowlist: the resolved picks and the
+   * registry's known names. Rendered per descriptor by
+   * renderSkillsSelection (pi loads each pick with discovery off; claude
+   * and codex turn the complement off); muse refuses. */
+  readonly skills?: SkillsSelection;
   readonly model?: string;
   readonly autonomy?: boolean;
   readonly effort?: string;
   readonly sandbox?: string;
+  readonly contextWindow?: number;
   readonly provider?: string;
   readonly discovery?: DiscoveryOptions;
   readonly write?: boolean;
@@ -81,11 +93,10 @@ export interface TurnOptions {
    * harness argv; the CLI layer turns it into the prompt preamble and
    * arms question-block detection. Undefined means the default: "ask". */
   readonly questions?: import("./question.js").QuestionMode;
-  /** Internal: set by CLI when prompt came from --prompt/--prompt-file to bypass leading '-' guard */
-  readonly __explicitPrompt?: boolean;
-  /** toolMap extensible vocabulary per harness (issue toolMap) */
-  readonly toolMap?: Readonly<Record<string, Readonly<Record<string, string>>>>;
-  readonly access?: "read" | "write";
+  /** The merged toolMap (every harness, native plus tier), the one shape
+   * past option resolution (RFC-02 change 8). */
+  readonly toolMap?: ToolMap;
+  readonly access?: AccessValue;
 }
 
 export interface ResumeOptions extends TurnOptions {
@@ -98,8 +109,8 @@ export type LaunchOptions = TurnOptions;
  * validated selections, with the variadic tools flag LAST and fed exactly
  * one joined token so nothing after it can be swallowed as a tool name. */
 const turnTail = (h: HarnessDescriptor, opts: TurnOptions): string[] => {
-  assertCleanPromptMaybe(h, opts.prompt, opts.__explicitPrompt);
-  const tail = [opts.prompt, ...h.launch.streamFlags];
+  assertCleanPrompt(h, opts.prompt);
+  const tail = [promptTextOf(opts), ...h.launch.streamFlags];
   if (opts.model !== undefined) {
     const validated = validateModel(h, opts.model);
     if (!validated.ok) {
@@ -127,15 +138,14 @@ const turnTail = (h: HarnessDescriptor, opts: TurnOptions): string[] => {
     tail.push(h.autonomy.flag);
   }
   if (opts.tools !== undefined || opts.excludeTools !== undefined) {
-    const perHarnessMap = opts.toolMap?.[h.name];
     const rendered = renderToolSelection(h, {
       include: opts.tools,
       exclude: opts.excludeTools,
-      toolMap: perHarnessMap,
+      toolMap: opts.toolMap,
     });
     tail.push(...rendered.tokens);
   }
-  if (opts.skills !== undefined && opts.skills.length > 0) {
+  if (opts.skills !== undefined) {
     tail.push(...renderSkillsSelection(h, opts.skills));
   }
   return tail;
@@ -186,6 +196,27 @@ export const buildResumeArgv = (h: HarnessDescriptor, opts: ResumeOptions): stri
   ];
 };
 
+/** What a spawn needs beyond the turn options: the session to resume, if
+ * any, and the raw passthrough tail (ADR 0003). */
+export interface SpawnArgvOptions extends TurnOptions {
+  readonly resume?: string;
+  readonly passthrough?: readonly string[];
+}
+
+/** The argv a turn spawns: launch or resume per `resume`, then the
+ * passthrough tail after a bare separator. One owner, so the CLI's preview
+ * and the runner's spawn agree by construction (RFC-02 change 10). */
+export const buildSpawnArgv = (h: HarnessDescriptor, opts: SpawnArgvOptions): string[] => {
+  assertIsolationCombination(h, opts);
+  const base =
+    opts.resume === undefined
+      ? buildLaunchArgv(h, opts)
+      : buildResumeArgv(h, { ...opts, sessionId: opts.resume });
+  return opts.passthrough !== undefined && opts.passthrough.length > 0
+    ? [...base, "--", ...opts.passthrough]
+    : base;
+};
+
 export interface SessionOptions {
   readonly sessionId: string;
   readonly model?: string;

package/src/interpretation/content.ts

@@ -10,8 +10,8 @@
  * payload-discriminated records - for the flat match/field spec that
  * identity decoding uses.)
  */
-import type { HarnessName } from "../knowledge/descriptor.js";
-import { asRecord } from "./shape.js";
+import type { HarnessName, LimitCode } from "../knowledge/descriptor.js";
+import { asRecord, readPath as at } from "./shape.js";
 
 export type ContentEvent =
   | { readonly kind: "token"; readonly text: string }
@@ -22,7 +22,16 @@ export type ContentEvent =
    * record); the runner turns it into a task failure. Other errors are
    * informational and the turn goes on. */
   | { readonly kind: "error"; readonly message: string; readonly terminal?: boolean }
-  | { readonly kind: "budget"; readonly detail: string };
+  | { readonly kind: "budget"; readonly detail: string }
+  /** A structured limit record on the stream (claude's rate_limit_event);
+   * the runner turns it into a limit-class failure. `resetsAt` is epoch
+   * milliseconds when the harness reported one. */
+  | {
+      readonly kind: "limit";
+      readonly code: LimitCode;
+      readonly detail: string;
+      readonly resetsAt?: number;
+    };
 
 /** Text of an array of `{type:"text", text}` content blocks. */
 const textOfBlocks = (content: unknown): string =>
@@ -34,16 +43,6 @@ const textOfBlocks = (content: unknown): string =>
         .join("")
     : "";
 
-const at = (record: Record<string, unknown>, path: string): unknown => {
-  let cursor: unknown = record;
-  for (const seg of path.split(".")) {
-    const inner = asRecord(cursor);
-    if (inner === null) return undefined;
-    cursor = inner[seg];
-  }
-  return cursor;
-};
-
 const claude = (r: Record<string, unknown>): ContentEvent[] => {
   const events: ContentEvent[] = [];
   if (r.type === "assistant") {
@@ -75,6 +74,24 @@ const claude = (r: Record<string, unknown>): ContentEvent[] => {
     // clean turn. (openSession handles result boundaries itself.)
     const sub = typeof r.subtype === "string" ? r.subtype : "result error";
     events.push({ kind: "error", message: `turn failed: ${sub}`, terminal: true });
+  } else if (r.type === "rate_limit_event") {
+    // Only "rejected" is a limit; "allowed_warning" still serves the request.
+    // overageStatus is a separate billing signal, not a rate limit.
+    // resetsAt arrives in seconds; the event carries milliseconds. No wall
+    // clock is read.
+    const info = asRecord(r.rate_limit_info);
+    const status = info?.status;
+    if (status === "rejected") {
+      const raw = info?.resetsAt;
+      const milliseconds = typeof raw === "number" ? raw * 1000 : Number.NaN;
+      const resetsAt = Number.isFinite(milliseconds) && milliseconds > 0 ? milliseconds : undefined;
+      events.push({
+        kind: "limit",
+        code: "rate-limit",
+        detail: `rate_limit_event status=${String(status)}`,
+        ...(resetsAt !== undefined ? { resetsAt } : {}),
+      });
+    }
   }
   return events;
 };

package/src/interpretation/hints.ts

@@ -6,10 +6,10 @@
  * stay-on-harness suggestion first. Wording is locked verbatim; unit tests
  * pin every string.
  */
-import type { HarnessDescriptor } from "../knowledge/descriptor.js";
+import { deepFreeze, type HarnessDescriptor } from "../knowledge/descriptor.js";
 import type { RefusalOption } from "./refusal.js";
 
-const HINTS: Readonly<Record<string, Readonly<Record<string, string>>>> = deepFreezeSafe({
+const HINTS: Readonly<Record<string, Readonly<Record<string, string>>>> = deepFreeze({
   claude: {
     sandbox:
       "claude has no sandbox modes; approximate with a per-tool allowlist (--tools Read,Bash) or --disallowedTools to keep tools out, and run untrusted work in a disposable directory or container",
@@ -84,16 +84,6 @@ const HINTS: Readonly<Record<string, Readonly<Record<string, string>>>> = deepFr
   },
 });
 
-/** deepFreeze without importing the descriptor's (which carries extra
- * machinery); structure is plain JSON so Object.freeze all the way down. */
-function deepFreezeSafe<T>(value: T): T {
-  if (typeof value === "object" && value !== null) {
-    for (const v of Object.values(value as Record<string, unknown>)) deepFreezeSafe(v);
-    Object.freeze(value);
-  }
-  return value;
-}
-
 /** The confirmed hint for a refused option on a harness, or undefined. */
 export const hintFor = (harness: string, option: RefusalOption): string | undefined =>
   HINTS[harness]?.[option];

package/src/interpretation/index.ts

@@ -10,7 +10,6 @@
 export * from "./argv.js";
 export * from "./capabilities.js";
 export * from "./context.js";
-export * from "./dimensions.js";
 export * from "./identity.js";
 export * from "./limits.js";
 export * from "./parse-resume.js";

package/src/interpretation/isolation.ts

@@ -0,0 +1,39 @@
+import type { HarnessDescriptor } from "../knowledge/descriptor.js";
+import type { TurnOptions } from "./argv.js";
+import { ArgvRefusalError } from "./refusal.js";
+
+/** Isolation owns these dimensions for the whole invocation. Config defaults
+ * yield to it; explicit competing selections refuse before registry reads. */
+export const ISOLATION_OVERRIDES = [
+  "tools",
+  "excludeTools",
+  "skills",
+  "access",
+  "autonomy",
+  "discovery",
+] as const;
+export const assertIsolationCombination = (
+  h: HarnessDescriptor,
+  opts: Partial<TurnOptions> & {
+    readonly skillNames?: readonly string[];
+    readonly passthrough?: readonly string[];
+  },
+): void => {
+  if (opts.isolation === undefined) return;
+  const conflict =
+    ISOLATION_OVERRIDES.find((key) =>
+      key === "autonomy" ? opts[key] === true : opts[key] !== undefined,
+    ) ??
+    (opts.skillNames !== undefined ? "skills" : undefined) ??
+    (opts.passthrough?.length ? "native passthrough" : undefined);
+  if (conflict === undefined) return;
+  throw new ArgvRefusalError({
+    issue: "mutually-exclusive-options",
+    harness: h.name,
+    option: "isolation",
+    detail: conflict,
+    supported: [
+      "tool-free without explicit tools, skills, access, autonomy, discovery, or native passthrough",
+    ],
+  });
+};

package/src/interpretation/limits.ts

@@ -25,18 +25,15 @@ import type {
   LimitMatcher,
   PhraseMatcher,
 } from "../knowledge/descriptor.js";
-import { SHARED_TRANSPORT_MATCHERS, SHARED_UNAVAILABLE_MATCHERS } from "../knowledge/matchers.js";
-
-/** Bottom-up batch scans stop after this many non-empty lines: the wall is
- * virtually always the last thing a dying turn printed, and an unbounded
- * scan over an accumulating session buffer is O(turns x output). */
-const BATCH_SCAN_MAX_LINES = 200;
-
-/** Max pattern length and max matchers per harness per kind - load-bearing
- * bounds that prevent a crafted override file from DoS'ing the matcher
- * compiler or the scanner. */
-const MAX_PATTERN_LENGTH = 200;
-const MAX_MATCHERS_PER_KIND = 64;
+import {
+  compileMatcher,
+  MAX_MATCHERS_PER_KIND,
+  SHARED_TRANSPORT_MATCHERS,
+  SHARED_UNAVAILABLE_MATCHERS,
+} from "../knowledge/matchers.js";
+
+/** The pattern bounds live with the matchers in the knowledge layer
+ * (compileMatcher); this is the per-line input window. */
 const WINDOW = 4096;
 
 // WeakMap cache: same matcher array instance reuses identical RegExp objects
@@ -49,24 +46,6 @@ const authCache = new WeakMap<
   ReadonlyArray<readonly [RegExp, AuthFailureKind]>
 >();
 
-const validateAndCompile = (pattern: string, flags: string | undefined): RegExp => {
-  const f = flags ?? "i";
-  if (pattern.length > MAX_PATTERN_LENGTH) {
-    throw new Error(`pattern over ${MAX_PATTERN_LENGTH} characters`);
-  }
-  if (f.includes("g") || f.includes("y")) {
-    throw new Error(`flags must not contain g or y (got ${JSON.stringify(f)})`);
-  }
-  for (const ch of f) {
-    if (!"imsu".includes(ch)) throw new Error(`flag ${JSON.stringify(ch)} outside imsu`);
-  }
-  try {
-    return new RegExp(pattern, f);
-  } catch (e) {
-    throw new Error(`uncompilable pattern ${JSON.stringify(pattern)}: ${(e as Error).message}`);
-  }
-};
-
 export const compileLimitMatchers = (
   matchers: ReadonlyArray<LimitMatcher>,
 ): ReadonlyArray<readonly [RegExp, LimitCode]> => {
@@ -75,7 +54,7 @@ export const compileLimitMatchers = (
   if (matchers.length > MAX_MATCHERS_PER_KIND) {
     throw new Error(`more than ${MAX_MATCHERS_PER_KIND} matchers per harness per kind`);
   }
-  const compiled = matchers.map((m) => [validateAndCompile(m.pattern, m.flags), m.code] as const);
+  const compiled = matchers.map((m) => [compileMatcher(m.pattern, m.flags), m.code] as const);
   limitCache.set(matchers, compiled);
   return compiled;
 };
@@ -88,27 +67,11 @@ export const compileAuthMatchers = (
   if (matchers.length > MAX_MATCHERS_PER_KIND) {
     throw new Error(`more than ${MAX_MATCHERS_PER_KIND} matchers per harness per kind`);
   }
-  const compiled = matchers.map((m) => [validateAndCompile(m.pattern, m.flags), m.kind] as const);
+  const compiled = matchers.map((m) => [compileMatcher(m.pattern, m.flags), m.kind] as const);
   authCache.set(matchers, compiled);
   return compiled;
 };
 
-// Generic alias for tests that call compileMatchers directly
-export const compileMatchers = <T extends LimitMatcher | AuthMatcher>(
-  matchers: ReadonlyArray<T>,
-): ReadonlyArray<readonly [RegExp, unknown]> => {
-  // Dispatch based on first element's shape - limit has code, auth has kind
-  if (matchers.length === 0) return [];
-  const first = matchers[0] as unknown as Record<string, unknown>;
-  if ("code" in first)
-    return compileLimitMatchers(
-      matchers as unknown as ReadonlyArray<LimitMatcher>,
-    ) as unknown as ReadonlyArray<readonly [RegExp, unknown]>;
-  return compileAuthMatchers(
-    matchers as unknown as ReadonlyArray<AuthMatcher>,
-  ) as unknown as ReadonlyArray<readonly [RegExp, unknown]>;
-};
-
 const scanLine = <Code>(
   line: string,
   matchers: ReadonlyArray<readonly [RegExp, Code]>,
@@ -121,40 +84,16 @@ const scanLine = <Code>(
   return null;
 };
 
-const scanTail = <Code>(
-  output: string,
-  matchers: ReadonlyArray<readonly [RegExp, Code]>,
-): Code | null => {
-  let end = output.length;
-  let scanned = 0;
-  while (end > 0 && scanned < BATCH_SCAN_MAX_LINES) {
-    const start = output.lastIndexOf("\n", end - 1);
-    const line = output.slice(start + 1, end).trim();
-    end = start;
-    if (line === "") continue;
-    scanned++;
-    const code = scanLine(line, matchers);
-    if (code !== null) return code;
-  }
-  return null;
-};
-
-/** Per-line entry point for streaming readers: O(1) per line, no rescans. */
+/** Per-line entry point for streaming readers: O(1) per line, no rescans.
+ * Both runners feed lines as they arrive; there is no batch form. */
 export const detectLimitInLine = (h: HarnessDescriptor, line: string): LimitCode | null =>
   scanLine(line.trim(), compileLimitMatchers(h.limitMatchers));
 
-/** Batch convenience over a turn's tail, bounded and bottom-up. */
-export const detectLimit = (h: HarnessDescriptor, output: string): LimitCode | null =>
-  scanTail(output, compileLimitMatchers(h.limitMatchers));
-
 export const detectAuthFailureInLine = (
   h: HarnessDescriptor,
   line: string,
 ): AuthFailureKind | null => scanLine(line.trim(), compileAuthMatchers(h.authMatchers));
 
-export const detectAuthFailure = (h: HarnessDescriptor, output: string): AuthFailureKind | null =>
-  scanTail(output, compileAuthMatchers(h.authMatchers));
-
 const phraseCache = new WeakMap<ReadonlyArray<PhraseMatcher>, ReadonlyArray<RegExp>>();
 
 const compilePhraseMatchers = (matchers: ReadonlyArray<PhraseMatcher>): ReadonlyArray<RegExp> => {
@@ -163,7 +102,7 @@ const compilePhraseMatchers = (matchers: ReadonlyArray<PhraseMatcher>): Readonly
   if (matchers.length > MAX_MATCHERS_PER_KIND) {
     throw new Error(`more than ${MAX_MATCHERS_PER_KIND} matchers per harness per kind`);
   }
-  const compiled = matchers.map((m) => validateAndCompile(m.pattern, m.flags));
+  const compiled = matchers.map((m) => compileMatcher(m.pattern, m.flags));
   phraseCache.set(matchers, compiled);
   return compiled;
 };

package/src/interpretation/question.ts

@@ -47,6 +47,12 @@ If and only if a genuine decision you cannot make defensibly blocks correct prog
 
 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.`;
 
+/** The wrapper hcn composes around the user's answer to an escalated
+ * question, so a consumer never re-derives it (RFC-01; the README quotes
+ * the exact text). One owner for both session surfaces. */
+export const composeAnswer = (question: string, answer: string): string =>
+  `The user answered the question: "${question}" with: ${answer}. Continue accordingly.`;
+
 export type QuestionMode = "ask" | "assume" | "none";
 
 export const QUESTION_MODES: readonly QuestionMode[] = ["ask", "assume", "none"] as const;
@@ -152,6 +158,46 @@ const parseBlock = (body: string): QuestionDetection => {
   };
 };
 
+/** What a turn's close found, recorded on `done` (RFC-01). */
+export type QuestionDetectionKind = "block" | "malformed" | "none";
+
+/** The typed question event a detected block becomes: the fields ARE the
+ * question; prose renders from them downstream. */
+export interface QuestionEvent {
+  readonly kind: "question";
+  readonly question: string;
+  readonly options: readonly string[];
+  readonly recommended?: string;
+}
+
+/** The one place a detected block becomes a question event (RFC-02
+ * change 5). Both runners call it at turn close with the last assistant
+ * message: detection is armed only in `ask` mode; a malformed block names
+ * its malformation and is never a silent no-op. */
+export const questionEventOf = (
+  lastAssistantText: string | null,
+  mode: QuestionMode,
+):
+  | { readonly detection: "none" }
+  | { readonly detection: "malformed"; readonly malformed: string }
+  | { readonly detection: "block"; readonly event: QuestionEvent } => {
+  if (mode !== "ask" || lastAssistantText === null) return { detection: "none" };
+  const detected = detectQuestionBlock(lastAssistantText);
+  if (detected === null) return { detection: "none" };
+  if ("malformed" in detected) return { detection: "malformed", malformed: detected.malformed };
+  return {
+    detection: "block",
+    event: {
+      kind: "question",
+      question: detected.block.question,
+      options: detected.block.options,
+      ...(detected.block.recommended !== undefined
+        ? { recommended: detected.block.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

package/src/interpretation/refusal.ts

@@ -36,14 +36,18 @@ export type RefusalOption =
   | "skills"
   | "autonomy"
   | "questions"
+  | "timeout"
   | `discovery.${string}`;
 
 /** One helper builds the message from the structured fields so message and
  * fields cannot drift. Every message names an alternative, not only a
- * negation, so an agent can pivot without reading the descriptor. */
+ * negation, so an agent can pivot without reading the descriptor. A
+ * refusal raised before a harness is chosen (argument parsing, config)
+ * passes no harness, and the message carries no harness fragment (RFC-02
+ * change 11) instead of naming one the caller never picked. */
 export const buildRefusalMessage = (
   issue: RefusalIssue,
-  harness: HarnessName,
+  harness: HarnessName | undefined,
   option?: RefusalOption,
   facet?: DiscoveryFacet,
   supported: readonly string[] = [],
@@ -58,42 +62,46 @@ export const buildRefusalMessage = (
       ? ` facet ${JSON.stringify(facet)}`
       : "";
   const detailSuffix = detail ? ` (${detail})` : "";
+  // The harness fragments: present only when a harness was chosen.
+  const who = harness ?? "the harness";
+  const onHarness = harness === undefined ? "" : ` on ${harness}`;
+  const forHarness = harness === undefined ? "" : ` for ${harness}`;
   switch (issue) {
     case "unsupported-option":
-      return `${harness} cannot express${optionPart}${detailSuffix}; ${supportedStr} - drop the option or route this work to a harness that supports it`;
+      return `${who} cannot express${optionPart}${detailSuffix}; ${supportedStr} - drop the option or route this work to a harness that supports it`;
     case "unsupported-option-facet":
-      return `${harness} cannot express discovery${facetSuffix}${detailSuffix}; ${supportedStr} - drop the facet or route this work to a harness that supports it`;
+      return `${who} cannot express discovery${facetSuffix}${detailSuffix}; ${supportedStr} - drop the facet or route this work to a harness that supports it`;
     case "unsupported-on-resume": {
       const name = option
         ? JSON.stringify(option) + (facet ? `:${facet}` : "")
         : facet
           ? JSON.stringify(facet)
           : "option";
-      return `${name} cannot be expressed on resume for ${harness}${detailSuffix}; ${supportedStr} - re-launch instead of resuming or drop the option`;
+      return `${name} cannot be expressed on resume${forHarness}${detailSuffix}; ${supportedStr} - re-launch instead of resuming or drop the option`;
     }
     case "invalid-option-value":
-      return `invalid value for${optionPart} on ${harness}${detailSuffix}; ${supportedStr} - use a supported value instead`;
+      return `invalid value for${optionPart}${onHarness}${detailSuffix}; ${supportedStr} - use a supported value instead`;
     case "unknown-effort":
-      return `unknown effort for ${harness}${detail ? ` ${JSON.stringify(detail)}` : ""}; ${supportedStr} - use one of the ladder values`;
+      return `unknown effort${forHarness}${detail ? ` ${JSON.stringify(detail)}` : ""}; ${supportedStr} - use one of the ladder values`;
     case "unknown-model":
-      return `unknown ${harness} model${detail ? ` ${JSON.stringify(detail)}` : ""}; ${supportedStr} - use one of the supported models`;
+      return `unknown ${harness === undefined ? "" : `${harness} `}model${detail ? ` ${JSON.stringify(detail)}` : ""}; ${supportedStr} - use one of the supported models`;
     case "invalid-env":
-      return `invalid env key or value for ${harness}${detailSuffix}; ${supportedStr} - keys must match ^[A-Za-z_][A-Za-z0-9_]*$ and contain no NUL`;
+      return `invalid env key or value${forHarness}${detailSuffix}; ${supportedStr} - keys must match ^[A-Za-z_][A-Za-z0-9_]*$ and contain no NUL`;
     case "invalid-tool-grant":
-      return `tool grant for ${harness} contains an empty entry or a comma; a blank tool flag value grants nothing detectable, and a comma inside one name silently splits the grant; ${supportedStr} - provide comma-free, non-empty tool names as separate entries`;
+      return `tool grant${forHarness} contains an empty entry or a comma; a blank tool flag value grants nothing detectable, and a comma inside one name silently splits the grant; ${supportedStr} - provide comma-free, non-empty tool names as separate entries`;
     case "unknown-tool-name":
-      return `${harness} cannot compute a tool complement around an unknown name${detailSuffix}; ${supportedStr} - exclude only curated names, or pass the unknown name through an include list instead`;
+      return `${who} cannot compute a tool complement around an unknown name${detailSuffix}; ${supportedStr} - exclude only curated names, or pass the unknown name through an include list instead`;
     case "mutually-exclusive-options":
-      return `${harness} cannot combine${optionPart}${detailSuffix}; ${supportedStr} - pass exactly one of them`;
+      return `${harness === undefined ? "cannot combine" : `${harness} cannot combine`}${optionPart}${detailSuffix}; ${supportedStr} - pass exactly one of them`;
     case "prompt-flag-injection":
-      return `positional prompt may not start with '-'; it would be parsed as a flag by ${harness}${detailSuffix}; ${supportedStr} - remove leading '-' or prefix with a space`;
+      return `positional prompt may not start with '-'; it would be parsed as a flag by ${who}${detailSuffix}; ${supportedStr} - remove leading '-' or prefix with a space`;
     case "no-autonomy-mode":
-      return `${harness} has no unattended-run flag; ${supportedStr} - drop autonomy or route to a supporting harness (claude --dangerously-skip-permissions, codex/muse --yolo)`;
+      return `${who} has no unattended-run flag; ${supportedStr} - drop autonomy or route to a supporting harness (claude --dangerously-skip-permissions, codex/muse --yolo)`;
     case "no-session-mode":
-      return `${harness} declares no persistent headless session mode; ${supportedStr} - use hcn run --resume <id>`;
+      return `${who} declares no persistent headless session mode; ${supportedStr} - use hcn run --resume <id>`;
     default: {
       const exhaustive: never = issue;
-      return `${exhaustive as string} for ${harness}${optionPart}${detailSuffix}; ${supportedStr}`;
+      return `${exhaustive as string}${forHarness}${optionPart}${detailSuffix}; ${supportedStr}`;
     }
   }
 };
@@ -101,7 +109,9 @@ export const buildRefusalMessage = (
 /** Raised when launch options would corrupt or subvert the spawned argv. */
 export class ArgvRefusalError extends Error {
   readonly issue: RefusalIssue;
-  readonly harness: HarnessName;
+  /** The harness the refusal is about; absent when it was raised before
+   * one was chosen (argument parsing, config loading). */
+  readonly harness?: HarnessName;
   readonly option?: RefusalOption;
   readonly facet?: DiscoveryFacet;
   readonly supported: readonly string[];
@@ -115,7 +125,7 @@ export class ArgvRefusalError extends Error {
   readonly hint?: string;
   constructor(args: {
     readonly issue: RefusalIssue;
-    readonly harness: HarnessName;
+    readonly harness?: HarnessName;
     readonly option?: RefusalOption;
     readonly facet?: DiscoveryFacet;
     readonly supported?: readonly string[];