@dungle-scrubs/harness-cli-normalizer 0.3.0 → 0.4.0

package/src/cli/config.ts

@@ -0,0 +1,166 @@
+/**
+ * User-level config: ~/.config/hcn/config.json (or $HCN_CONFIG_DIR for
+ * tests). Hard-fail discipline: unknown keys, malformed JSON, and schema
+ * version mismatches exit 2 naming the offender - a config that silently
+ * no-ops is a safety hole in a tool whose config can tighten a sandbox.
+ *
+ * Schema is intentionally minimal and mirrors the normalized option
+ * surface; it grows as dimensions ratify. The parser validates SHAPE
+ * (key known, value type plausible); value legality (effort in ladder,
+ * model in vocabulary) is enforced by the same renderers as args, so
+ * config and CLI can never disagree about what is legal.
+ */
+import { existsSync, readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join, resolve } from "node:path";
+import type { TurnOptions } from "../interpretation/argv.js";
+
+const SCHEMA_VERSION = 1;
+
+export class ConfigError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "ConfigError";
+  }
+}
+
+export const userConfigPath = (): string =>
+  join(
+    process.env.HCN_CONFIG_DIR ??
+      join(process.env.XDG_CONFIG_HOME ?? join(homedir(), ".config"), "hcn"),
+    "config.json",
+  );
+
+/** Project config: `.hcn/config.json` at the git root (P4 ratified as A -
+ * auto-discover, no trust gate; the config is code-reviewed like AGENTS.md
+ * and every project-tier provenance line names its path). Null outside a
+ * repo or when the repo declares none. */
+export const projectConfigPath = (startDir: string = process.cwd()): string | null => {
+  let dir = resolve(startDir);
+  for (;;) {
+    if (existsSync(join(dir, ".hcn", "config.json"))) return join(dir, ".hcn", "config.json");
+    const parent = dirname(dir);
+    if (parent === dir) return null;
+    // stop at the git root: above it is not this project
+    if (existsSync(join(dir, ".git")) && !existsSync(join(parent, ".git"))) {
+      return null;
+    }
+    dir = parent;
+  }
+};
+
+type MutableTurnOptions = {
+  [K in keyof TurnOptions]?: TurnOptions[K];
+};
+
+const KNOWN_KEYS = new Set([
+  "effort",
+  "model",
+  "provider",
+  "sandbox",
+  "tools",
+  "excludeTools",
+  "autonomy",
+  "write",
+  "shell",
+  "maxSteps",
+  "toolsets",
+]);
+
+const LIST_KEYS = new Set(["tools", "excludeTools"]);
+const BOOL_KEYS = new Set(["autonomy", "write", "shell"]);
+
+/** Parse + validate config text. Throws ConfigError with the offending key
+ * named on any violation - never warns and continues. */
+export const parseUserConfig = (text: string): Partial<TurnOptions> => {
+  let raw: unknown;
+  try {
+    raw = JSON.parse(text);
+  } catch (e) {
+    throw new ConfigError(`config is not valid JSON: ${(e as Error).message}`);
+  }
+  if (typeof raw !== "object" || raw === null || Array.isArray(raw)) {
+    throw new ConfigError("config root must be a JSON object");
+  }
+  const obj = raw as Record<string, unknown>;
+
+  if (obj.version === undefined) {
+    throw new ConfigError("config missing required field: version");
+  }
+  if (obj.version !== SCHEMA_VERSION) {
+    throw new ConfigError(
+      `config version ${JSON.stringify(obj.version)} not supported (expected ${SCHEMA_VERSION})`,
+    );
+  }
+  delete obj.version;
+
+  const out: MutableTurnOptions = {};
+  for (const [key, value] of Object.entries(obj)) {
+    if (!KNOWN_KEYS.has(key)) {
+      throw new ConfigError(`unknown config key: ${JSON.stringify(key)}`);
+    }
+    if (key === "toolsets") {
+      if (
+        typeof value !== "object" ||
+        value === null ||
+        Array.isArray(value) ||
+        Object.entries(value).some(
+          ([, v]) => !Array.isArray(v) || v.some((t) => typeof t !== "string" || t.trim() === ""),
+        )
+      ) {
+        throw new ConfigError(
+          'config key "toolsets" must be an object of name -> non-empty string array',
+        );
+      }
+      (out as Record<string, unknown>)[key] = value;
+      continue;
+    }
+    if (LIST_KEYS.has(key)) {
+      if (!Array.isArray(value) || value.some((v) => typeof v !== "string")) {
+        throw new ConfigError(`config key ${JSON.stringify(key)} must be an array of strings`);
+      }
+      (out as Record<string, unknown>)[key] = value;
+      continue;
+    }
+    if (BOOL_KEYS.has(key)) {
+      if (typeof value !== "boolean") {
+        throw new ConfigError(`config key ${JSON.stringify(key)} must be a boolean`);
+      }
+      (out as Record<string, unknown>)[key] = value;
+      continue;
+    }
+    if (typeof value !== "string" && typeof value !== "number") {
+      throw new ConfigError(
+        `config key ${JSON.stringify(key)} must be a string or number, got ${typeof value}`,
+      );
+    }
+    (out as Record<string, unknown>)[key] = value;
+  }
+  return out as Partial<TurnOptions>;
+};
+
+/** Load the user config if the file exists; absent file is an empty config
+ * (no tiers engaged), unreadable or invalid file is a hard error. */
+export const loadUserConfig = (): { config: Partial<TurnOptions>; path: string } | null =>
+  loadConfigAt(userConfigPath());
+
+/** Load the project config (git-root auto-discovery, ratified A). */
+export const loadProjectConfig = (
+  startDir?: string,
+): { config: Partial<TurnOptions>; path: string } | null => {
+  const path = projectConfigPath(startDir);
+  if (path === null) return null;
+  return loadConfigAt(path);
+};
+
+const loadConfigAt = (path: string): { config: Partial<TurnOptions>; path: string } | null => {
+  let text: string;
+  try {
+    text = readFileSync(path, "utf8");
+  } catch (e) {
+    const code = (e as NodeJS.ErrnoException).code;
+    if (code === "ENOENT") return null;
+    throw new ConfigError(`cannot read config at ${path}: ${(e as Error).message}`);
+  }
+  return { config: parseUserConfig(text), path };
+};

package/src/cli/index.ts

@@ -1,4 +1,7 @@
 #!/usr/bin/env node
+import { realpathSync } from "node:fs";
+import { resolve } from "node:path";
+import { pathToFileURL } from "node:url";
 import { TOP_LEVEL_HELP } from "./help.js";
 import { getVersion } from "./version.js";
 
@@ -155,23 +158,33 @@ export const dispatch = async (raw: string[]): Promise<void> => {
   }
 };
 
-const main = async (): Promise<void> => {
+export const main = async (): Promise<void> => {
   await dispatch(process.argv.slice(2));
 };
 
-const shouldAutoRun = (() => {
-  const entry = process.argv[1] ?? "";
-  return (
-    entry.endsWith("cli.js") || entry.endsWith("cli/index.js") || entry.endsWith("src/cli/index.ts")
-  );
-})();
-
-if (shouldAutoRun) {
-  main().catch((err) => {
+// The bin entry invokes this directly. Auto-run below covers direct
+// execution of this module itself (node dist/cli/index.js, bun src/cli/index.ts).
+export const run = (): void => {
+  main().catch((err: unknown) => {
     const message = err instanceof Error ? err.message : String(err);
     process.stderr.write(`fatal: ${message}\n`);
     if (err instanceof Error && err.stack) process.stderr.write(`${err.stack}\n`);
     process.exitCode = 1;
-    if (process.exitCode === 0) process.exitCode = 1;
   });
-}
+};
+
+// Run only when this module is the process main entry. process.argv[1] is
+// the path as invoked - a bin symlink such as npm's `hcn` keeps its link
+// name - while import.meta.url is this file's realpath, so resolving argv[1]
+// the same way survives symlinks. Filename suffix sniffing cannot (issue #33).
+const isMainEntry = (() => {
+  const entry = process.argv[1];
+  if (!entry) return false;
+  try {
+    return import.meta.url === pathToFileURL(realpathSync(resolve(entry))).href;
+  } catch {
+    return false;
+  }
+})();
+
+if (isMainEntry) run();

package/src/cli/inspect.ts

@@ -1,6 +1,7 @@
 import { redactArgv } from "../execution/stream-turn.js";
 import { buildLaunchArgv } from "../interpretation/argv.js";
 import { ArgvRefusalError } from "../interpretation/refusal.js";
+import { FloorExceededError, resolveEffectiveOptions } from "../interpretation/resolve-options.js";
 import { parseTurnOptions, resolvePromptAsync } from "./args.js";
 import { resolveHarness } from "./resolve-harness.js";
 
@@ -123,8 +124,40 @@ export const inspect = async (harnessName: string, rawArgs: string[]): Promise<v
     throw err;
   }
 
+  // Inspect resolves exactly as a launch would: profile + user config,
+  // launch-only semantics, so --argv previews the truth of a bare run.
+  const { loadUserConfig, loadProjectConfig, ConfigError } = await import("./config.js");
+  const tiers: {
+    user?: Partial<ReturnType<typeof parseTurnOptions>>;
+    project?: Partial<ReturnType<typeof parseTurnOptions>>;
+  } = {};
+  try {
+    const loaded = loadUserConfig();
+    if (loaded !== null) tiers.user = loaded.config;
+    const proj = loadProjectConfig();
+    if (proj !== null) tiers.project = proj.config;
+  } catch (configErr) {
+    if (configErr instanceof ConfigError) {
+      process.stderr.write(`config error: ${(configErr as Error).message}\n`);
+      process.exitCode = 2;
+      return;
+    }
+    throw configErr;
+  }
+  let resolved: ReturnType<typeof resolveEffectiveOptions>;
+  try {
+    resolved = resolveEffectiveOptions(h, { ...turnOpts, prompt } as never, tiers);
+  } catch (resErr) {
+    if (resErr instanceof FloorExceededError) {
+      process.stderr.write(`${(resErr as Error).message}\n`);
+      process.exitCode = 2;
+      return;
+    }
+    throw resErr;
+  }
+  const { prompt: _p, ...effectiveRest } = resolved.options as { prompt: string };
   const fullOpts = {
-    ...turnOpts,
+    ...(effectiveRest as object),
     prompt,
     ...(promptSource !== "positional" ? { __explicitPrompt: true as const } : {}),
   } as Parameters<typeof buildLaunchArgv>[1];

package/src/cli/render.ts

@@ -41,7 +41,16 @@ export const renderEvent = (event: HarnessEvent, state: RenderState): void => {
       break;
     case "failure": {
       const detail = event.message ?? `${event.class}`;
-      process.stdout.write(red(`\n  ✗ failure ${event.class}: ${detail}`));
+      // D6: native failures get an unmistakable prefix and the native exit
+      // code shown as data, so a human never reads a harness error as an
+      // hcn error.
+      if (event.class === "native") {
+        const nat =
+          event.nativeExitCode !== undefined ? ` [native exit ${event.nativeExitCode}]` : "";
+        process.stdout.write(red(`\n  ✗ NATIVE${nat} ${detail}`));
+      } else {
+        process.stdout.write(red(`\n  ✗ failure ${event.class}: ${detail}`));
+      }
       break;
     }
     case "done": {

package/src/cli/run.ts

@@ -3,6 +3,13 @@ import { nodeRunnerDeps } from "../execution/node-deps.js";
 import { KILL_GRACE_MS, redactArgv, streamTurn } from "../execution/stream-turn.js";
 import { buildLaunchArgv, buildResumeArgv } from "../interpretation/argv.js";
 import { ArgvRefusalError } from "../interpretation/refusal.js";
+import {
+  FloorExceededError,
+  type ProvenanceEntry,
+  resolveEffectiveOptions,
+} from "../interpretation/resolve-options.js";
+import { recognizeNativeSpelling, supportedBy } from "../interpretation/support.js";
+import { defaultDescriptors } from "../knowledge/overrides.js";
 import { parseRunExtra, parseTurnOptions, resolvePromptAsync } from "./args.js";
 import { createRenderState, renderEvent, writeEventNdjson } from "./render.js";
 import { resolveHarness } from "./resolve-harness.js";
@@ -16,7 +23,10 @@ export const run = async (harnessName: string, rawArgs: string[]): Promise<void>
     return;
   }
 
-  const { parseCommonFlags, detectPositionalPromptInjection } = await import("./args.js");
+  const { parseCommonFlags, detectPositionalPromptInjection, splitPassthrough } = await import(
+    "./args.js"
+  );
+  const { passthrough } = splitPassthrough(rawArgs);
   const injection = detectPositionalPromptInjection(rawArgs);
   if (injection) {
     const err = new ArgvRefusalError({
@@ -35,7 +45,52 @@ export const run = async (harnessName: string, rawArgs: string[]): Promise<void>
     parsed = parseCommonFlags(rawArgs);
   } catch (err) {
     const message = err instanceof Error ? err.message : String(err);
-    process.stderr.write(`unknown flag: ${message}\n`);
+    // D7 part B: a native spelling passed before the separator gets
+    // recognized and redirected to the normalized flag instead of a
+    // generic unknown-flag error.
+    // parseArgs reports unknown long flags as "Unknown option '--x'" but
+    // splits bundled short flags ("-nt" -> "Unknown option 'n'"). Match the
+    // reported token back against the ORIGINAL argv: a short-flag bundle
+    // that some descriptor spells exactly (pi's -nt) is recognizable; a
+    // lone unknown token keeps the plain error.
+    const flagMatch = message.match(/Unknown option '([A-Za-z0-9_-]+)'/);
+    let rawFlag: string | undefined;
+    if (flagMatch?.[1] !== undefined) {
+      const reported = flagMatch[1].startsWith("-") ? flagMatch[1] : `-${flagMatch[1]}`;
+      // Exact long flag: use it. Reported short flag (e.g. -n): the caller
+      // may have typed a BUNDLE (-nt) that parseArgs split - find the argv
+      // token that starts with the reported short and is longer; recognition
+      // then decides whether the whole bundle is a descriptor spelling.
+      const fromArgv =
+        rawArgs.find((a) => a === reported) ??
+        (reported.length === 2
+          ? rawArgs.find((a) => a.length > 2 && a.startsWith(reported))
+          : undefined);
+      rawFlag = fromArgv ?? reported;
+    }
+    const native =
+      rawFlag !== undefined ? recognizeNativeSpelling(defaultDescriptors(), rawFlag) : null;
+    if (native !== null) {
+      const by = native.option.startsWith("discovery.")
+        ? native.entries
+        : supportedBy(defaultDescriptors(), native.option);
+      const normalizedSpelling =
+        native.option === "excludeTools"
+          ? "--exclude-tools"
+          : native.option.startsWith("discovery.")
+            ? `--no-${native.option.split(".")[1] === "instructionFiles" ? "instruction-files" : native.option.split(".")[1]}`
+            : `--${native.option}`;
+      process.stderr.write(
+        `unknown flag: ${rawFlag} is a native spelling (used by ${native.entries.map((e) => e.harness).join(", ")}) - use the normalized ${normalizedSpelling} flag instead\n`,
+      );
+      if (by.length > 0) {
+        process.stderr.write(
+          `supported on: ${by.map((e) => `${e.harness} (${e.spelling})`).join(", ")}\n`,
+        );
+      }
+    } else {
+      process.stderr.write(`unknown flag: ${message}\n`);
+    }
     process.stderr.write(`Run 'hcn run --help' for usage.\n`);
     process.exitCode = 2;
     return;
@@ -50,6 +105,11 @@ export const run = async (harnessName: string, rawArgs: string[]): Promise<void>
     process.exitCode = 2;
     return;
   }
+  if (passthrough.length === 0 && rawArgs.includes("--")) {
+    process.stderr.write(`-- separator given but no passthrough tokens followed it\n`);
+    process.exitCode = 2;
+    return;
+  }
 
   const wantJson = values.json === true;
 
@@ -67,6 +127,12 @@ export const run = async (harnessName: string, rawArgs: string[]): Promise<void>
   } catch (err) {
     if (err instanceof ArgvRefusalError) {
       process.stderr.write(`${err.message}\n`);
+      if (err.hint) process.stderr.write(`hint: ${err.hint}\n`);
+      if (err.supportedBy?.length) {
+        process.stderr.write(
+          `supported on: ${err.supportedBy.map((e) => `${e.harness} (${e.spelling})`).join(", ")}\n`,
+        );
+      }
       if (err.supported.length) process.stderr.write(`supported: ${err.supported.join(", ")}\n`);
       process.exitCode = 2;
       return;
@@ -86,6 +152,12 @@ export const run = async (harnessName: string, rawArgs: string[]): Promise<void>
   } catch (err) {
     if (err instanceof ArgvRefusalError) {
       process.stderr.write(`${err.message}\n`);
+      if (err.hint) process.stderr.write(`hint: ${err.hint}\n`);
+      if (err.supportedBy?.length) {
+        process.stderr.write(
+          `supported on: ${err.supportedBy.map((e) => `${e.harness} (${e.spelling})`).join(", ")}\n`,
+        );
+      }
       if (err.supported.length) process.stderr.write(`supported: ${err.supported.join(", ")}\n`);
       process.exitCode = 2;
       return;
@@ -99,6 +171,12 @@ export const run = async (harnessName: string, rawArgs: string[]): Promise<void>
   } catch (err) {
     if (err instanceof ArgvRefusalError) {
       process.stderr.write(`${err.message}\n`);
+      if (err.hint) process.stderr.write(`hint: ${err.hint}\n`);
+      if (err.supportedBy?.length) {
+        process.stderr.write(
+          `supported on: ${err.supportedBy.map((e) => `${e.harness} (${e.spelling})`).join(", ")}\n`,
+        );
+      }
       if (err.supported.length) process.stderr.write(`supported: ${err.supported.join(", ")}\n`);
       process.exitCode = 2;
       return;
@@ -107,20 +185,84 @@ export const run = async (harnessName: string, rawArgs: string[]): Promise<void>
   }
 
   const isExplicit = promptSource !== "positional";
+
+  // Defaults profile + user config: LAUNCH-ONLY. A resumed session keeps
+  // its own settings; the resolver never runs on resume paths.
+  let resolvedProvenance: readonly ProvenanceEntry[] = [];
+  let resolvedUnrenderable: readonly string[] = [];
+  let effectiveTurnOpts: ReturnType<typeof parseTurnOptions> = turnOpts;
+  if (extra.resume === undefined) {
+    const tiers: {
+      user?: Partial<ReturnType<typeof parseTurnOptions>>;
+      project?: Partial<ReturnType<typeof parseTurnOptions>>;
+    } = {};
+    const { loadUserConfig, loadProjectConfig, ConfigError } = await import("./config.js");
+    try {
+      const loaded = loadUserConfig();
+      if (loaded !== null) tiers.user = loaded.config;
+      const proj = loadProjectConfig();
+      if (proj !== null) tiers.project = proj.config;
+    } catch (configErr) {
+      if (configErr instanceof ConfigError) {
+        process.stderr.write(`config error: ${(configErr as Error).message}\n`);
+        process.exitCode = 2;
+        return;
+      }
+      throw configErr;
+    }
+    let resolved: ReturnType<typeof resolveEffectiveOptions>;
+    try {
+      resolved = resolveEffectiveOptions(h, { ...turnOpts, prompt } as never, tiers);
+    } catch (resErr) {
+      if (resErr instanceof FloorExceededError) {
+        process.stderr.write(`${(resErr as Error).message}\n`);
+        process.exitCode = 2;
+        return;
+      }
+      throw resErr;
+    }
+    const { provenance, unrenderable } = resolved;
+    resolvedProvenance = provenance;
+    resolvedUnrenderable = unrenderable;
+    const { prompt: _p, ...rest } = resolved.options as { prompt: string };
+    effectiveTurnOpts = rest as ReturnType<typeof parseTurnOptions>;
+    // Provenance is diagnostic data like the spawn line - stderr in BOTH
+    // render modes, never stdout (stdout carries the NDJSON contract).
+    if (provenance.length > 0 || unrenderable.length > 0) {
+      for (const entry of provenance) {
+        process.stderr.write(
+          `provenance: ${entry.key} = ${JSON.stringify(entry.value)} (${entry.tier})\n`,
+        );
+      }
+      for (const key of unrenderable) {
+        process.stderr.write(
+          `divergence: profile ${JSON.stringify(key)} not expressible on ${h.name}; harness default applies\n`,
+        );
+      }
+    }
+  }
+
   const fullOpts = {
-    ...turnOpts,
+    ...effectiveTurnOpts,
     prompt,
     cwd: extra.cwd,
     env: extra.env,
     resume: extra.resume,
+    ...(passthrough.length > 0 ? { passthrough } : {}),
     ...(isExplicit ? { __explicitPrompt: true as const } : {}),
-  } as Parameters<typeof streamTurn>[1] & { resume?: string; __explicitPrompt?: boolean };
+  } as Parameters<typeof streamTurn>[1] & {
+    resume?: string;
+    __explicitPrompt?: boolean;
+    passthrough?: readonly string[];
+  };
 
   // Pre-validate via building argv to catch refusals before spawn (so we don't spawn on bad args)
   let _validated = false;
   let preArgv: string[] | null = null;
   try {
     if (fullOpts.resume) {
+      // Resume never carries profile/config resolution (launch-only rule),
+      // so it builds from the raw turn options.
       preArgv = buildResumeArgv(h, {
         ...(turnOpts as object),
         prompt,
@@ -128,8 +270,10 @@ export const run = async (harnessName: string, rawArgs: string[]): Promise<void>
         __explicitPrompt: isExplicit,
       } as never);
     } else {
+      // Launch builds from the RESOLVED options so the spawn line and the
+      // real argv agree.
       preArgv = buildLaunchArgv(h, {
-        ...(turnOpts as object),
+        ...(effectiveTurnOpts as object),
         prompt,
         __explicitPrompt: isExplicit,
       } as never);
@@ -138,6 +282,12 @@ export const run = async (harnessName: string, rawArgs: string[]): Promise<void>
   } catch (err) {
     if (err instanceof ArgvRefusalError) {
       process.stderr.write(`${err.message}\n`);
+      if (err.hint) process.stderr.write(`hint: ${err.hint}\n`);
+      if (err.supportedBy?.length) {
+        process.stderr.write(
+          `supported on: ${err.supportedBy.map((e) => `${e.harness} (${e.spelling})`).join(", ")}\n`,
+        );
+      }
       if (err.supported.length) process.stderr.write(`supported: ${err.supported.join(", ")}\n`);
       process.exitCode = 2;
       return;
@@ -234,6 +384,12 @@ export const run = async (harnessName: string, rawArgs: string[]): Promise<void>
   } catch (err) {
     if (err instanceof ArgvRefusalError) {
       process.stderr.write(`${err.message}\n`);
+      if (err.hint) process.stderr.write(`hint: ${err.hint}\n`);
+      if (err.supportedBy?.length) {
+        process.stderr.write(
+          `supported on: ${err.supportedBy.map((e) => `${e.harness} (${e.spelling})`).join(", ")}\n`,
+        );
+      }
       if (err.supported.length) process.stderr.write(`supported: ${err.supported.join(", ")}\n`);
       process.exitCode = 2;
       process.off("SIGINT", onSig);

package/src/execution/failure.ts

@@ -30,6 +30,7 @@ export const FAILURE_CLASSES = Object.freeze([
   "task",
   "transport",
   "rejected",
+  "native",
 ] as const);
 export type FailureClass = (typeof FAILURE_CLASSES)[number];
 
@@ -41,13 +42,21 @@ export interface FailureSummary {
   readonly authKind?: AuthFailureKind;
   readonly resetsAt?: number;
   readonly issue?: RefusalIssue;
-  readonly option?: TurnOptionKey;
+  readonly option?: import("../interpretation/refusal.js").RefusalOption;
   readonly facet?: DiscoveryFacet;
   readonly supported?: readonly string[];
+  /** D7: cross-harness support entries derived from descriptors. */
+  readonly supportedBy?: ReadonlyArray<{ harness: string; spelling: string }>;
+  /** D8: nearest-alternative hint for the current harness. */
+  readonly hint?: string;
+  /** D6: the harness process's own exit code for a native failure - data,
+   * because native conventions differ from hcn's (codex usage errors exit
+   * 2, which hcn reserves for refusals). */
+  readonly nativeExitCode?: number;
 }
 
 export const retryableOf = (cls: FailureClass): boolean =>
-  cls !== "task" && cls !== "budget" && cls !== "rejected";
+  cls !== "task" && cls !== "budget" && cls !== "rejected" && cls !== "native";
 
 const messageFor = (cls: FailureClass, detail?: string): string => {
   switch (cls) {
@@ -67,10 +76,30 @@ const messageFor = (cls: FailureClass, detail?: string): string => {
       return `Transport failure${detail ? ` (${detail})` : ""} - retry or route to another provider`;
     case "rejected":
       return `Request rejected${detail ? ` (${detail})` : ""} - change options or harness`;
+    case "native":
+      // D6: labeled NATIVE so it can never be confused with an hcn error.
+      // The harness's own message follows verbatim; the process exit code
+      // rides as data (nativeExitCode), because harness conventions differ
+      // (codex exits 2 on usage errors - the same code hcn uses for
+      // refusals, so hcn owns its own exit code and reports the native one).
+      return `NATIVE ERROR from harness${detail ? `: ${detail}` : ""} - the harness rejected or failed on its own arguments; this is not an hcn error`;
     default:
       return `Failure${detail ? ` (${detail})` : ""}`;
   }
-};
+}; /** D6: a failure that belongs to the harness, not hcn. Carries the
+ * native stderr verbatim and the native exit code as data. */
+export const failureFromNative = (
+  nativeExitCode: number | null,
+  stderrTail: readonly string[],
+): FailureSummary => ({
+  class: "native",
+  retryable: false,
+  message: messageFor(
+    "native",
+    stderrTail.slice(-3).join(" | ").slice(0, 512) || `exit ${nativeExitCode}`,
+  ),
+  nativeExitCode: nativeExitCode ?? undefined,
+});
 
 export const failureFromLimit = (code: LimitCode): FailureSummary => {
   const cls: FailureClass =
@@ -114,18 +143,25 @@ export const failureFromTransport = (detail?: string): FailureSummary => ({
 
 export const failureFromRejected = (opts: {
   issue: RefusalIssue;
-  option?: TurnOptionKey;
+  option?: import("../interpretation/refusal.js").RefusalOption;
   facet?: DiscoveryFacet;
   supported?: readonly string[];
+  supportedBy?: ReadonlyArray<{ harness: string; spelling: string }>;
+  hint?: string;
   detail?: string;
 }): FailureSummary => ({
   class: "rejected",
   retryable: false,
+  // D8: hint first, support list second - prose order matches the
+  // structured fields so an agent scanning the message hits the
+  // stay-on-harness suggestion before the switch temptation.
   message: messageFor("rejected", opts.detail ?? opts.issue),
   issue: opts.issue,
   option: opts.option,
   facet: opts.facet,
   supported: opts.supported,
+  supportedBy: opts.supportedBy,
+  hint: opts.hint,
 });
 
 /** Precedence for reduction: lower number = higher priority (wins). */
@@ -137,7 +173,10 @@ const PRECEDENCE: Record<FailureClass, number> = {
   budget: 3,
   task: 3,
   transport: 4,
-  rejected: 0, // rejected is separate, not reduced with others? But per spec, rejected is non-retryable and stands alone
+  // rejected stands alone (checked before precedence applies); native is
+  // terminal-by-classification, never reduced into anything else.
+  rejected: 0,
+  native: 0,
 };
 
 export const reduceFailures = (failures: readonly FailureSummary[]): FailureSummary | undefined => {