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

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 => {

package/src/execution/stream-turn.ts

@@ -28,6 +28,7 @@ import type { FailureSummary } from "./failure.js";
 import {
   failureFromAuth,
   failureFromLimit,
+  failureFromNative,
   failureFromRejected,
   failureFromTransport,
   reduceFailures,
@@ -96,6 +97,10 @@ export interface TurnRunOptions extends LaunchOptions {
   readonly cwd?: string;
   /** Per-call environment, merged over parent; "" deletes. */
   readonly env?: Readonly<Record<string, string>>;
+  /** D6 passthrough: raw harness tokens appended verbatim after the
+   * normalized argv. Wrong-harness flags here fail in the harness itself
+   * and surface as native errors - hcn never validates them. */
+  readonly passthrough?: readonly string[];
 }
 
 export async function* streamTurn(
@@ -144,6 +149,9 @@ export async function* streamTurn(
       opts.resume === undefined
         ? buildLaunchArgv(h, opts)
         : buildResumeArgv(h, { ...opts, sessionId: opts.resume });
+    if (opts.passthrough !== undefined && opts.passthrough.length > 0) {
+      argv = [...argv, "--", ...opts.passthrough];
+    }
     granularity = streamingGranularityOf(h, argv);
   } catch (e) {
     if (e instanceof ArgvRefusalError) {
@@ -152,6 +160,8 @@ export async function* streamTurn(
         option: e.option,
         facet: e.facet,
         supported: e.supported,
+        supportedBy: e.supportedBy,
+        hint: e.hint,
         detail: e.message,
       });
       // No process spawned on a refusal - log rejected instead of spawn
@@ -400,7 +410,12 @@ export async function* streamTurn(
   try {
     for await (const event of queue) yield event;
 
-    // Post-queue failure sources: nonzero exit with no other failure is transport
+    // Post-queue failure sources. Nonzero exit with no other failure and a
+    // non-empty stderr tail is a NATIVE failure (D6): the harness rejected
+    // its own arguments or crashed on them - verbatim stderr, native exit
+    // code as data, hcn exit 1. Without a stderr tail it stays transport
+    // (a silent nonzero exit reads as an environment problem, not a
+    // harness judgment).
     if (
       failures.length === 0 &&
       exitCode !== 0 &&
@@ -408,7 +423,11 @@ export async function* streamTurn(
       !killedByWatchdog &&
       !state.limitSeen
     ) {
-      const f = failureFromTransport(`nonzero exit ${exitCode}`);
+      const tailForNative = stderrTail.snapshot();
+      const f =
+        tailForNative.length > 0
+          ? failureFromNative(exitCode, tailForNative)
+          : failureFromTransport(`nonzero exit ${exitCode}`);
       failures.push(f);
       // Need to emit this failure before done, even though queue is closed
       yield { kind: "failure", ...f };
@@ -451,7 +470,18 @@ export async function* streamTurn(
       yield { kind: "error", message: tail.join("\n").slice(0, 4096) };
     }
     terminalEventReached = true;
-    yield { kind: "done", exitCode, cause, ...(reduced ? { failure: reduced } : {}) };
+    // D6: when the failure is native, the harness's own exit convention is
+    // DATA (nativeExitCode on the failure), not the done event's contract -
+    // hcn owns the process exit code (1 for any native failure) because
+    // harness conventions collide with hcn's (codex usage errors exit 2,
+    // which hcn reserves for refusals).
+    const nativeReduced = reduced?.class === "native";
+    yield {
+      kind: "done",
+      exitCode: nativeReduced ? null : exitCode,
+      cause,
+      ...(reduced ? { failure: reduced } : {}),
+    };
   } finally {
     const abandoned = !terminalEventReached;
     cancelled = true;

package/src/interpretation/argv.ts

@@ -5,8 +5,11 @@
  * no caller re-derives them.
  */
 import type { HarnessDescriptor, StreamingGranularity } from "../knowledge/descriptor.js";
+import { defaultDescriptors } from "../knowledge/overrides.js";
 import { ArgvRefusalError } from "./refusal.js";
 import { assertUsableSessionId } from "./session-id.js";
+import { supportedBy } from "./support.js";
+import { renderToolSelection } from "./tool-selection.js";
 import { renderTurnOptions } from "./turn-options.js";
 import { validateModel } from "./vocabulary.js";
 
@@ -50,6 +53,7 @@ export interface DiscoveryOptions {
 export interface TurnOptions {
   readonly prompt: string;
   readonly tools?: readonly string[];
+  readonly excludeTools?: readonly string[];
   readonly model?: string;
   readonly autonomy?: boolean;
   readonly effort?: string;
@@ -90,32 +94,23 @@ const turnTail = (h: HarnessDescriptor, opts: TurnOptions): string[] => {
   }
   if (opts.autonomy === true) {
     if (h.autonomy === null) {
+      const by = supportedBy(defaultDescriptors(), "autonomy");
       throw new ArgvRefusalError({
         issue: "no-autonomy-mode",
         harness: h.name,
-        supported: ["claude --dangerously-skip-permissions", "codex --yolo", "muse --yolo"],
+        supported: by.map((e) => `${e.harness} ${e.spelling}`),
+        supportedBy: by,
+        hint: "pi has no unattended-run flag; approximate with a per-tool allowlist (--tools read,bash) if you need unattended behavior on pi",
       });
     }
     tail.push(h.autonomy.flag);
   }
-  if (opts.tools !== undefined) {
-    if (h.launch.toolsFlag === null) {
-      throw new ArgvRefusalError({
-        issue: "unsupported-option",
-        harness: h.name,
-        supported: ["--allowedTools is claude-only"],
-        detail: "tools",
-      });
-    }
-    if (opts.tools.length === 0 || opts.tools.some((t) => t.trim() === "" || t.includes(","))) {
-      throw new ArgvRefusalError({
-        issue: "invalid-tool-grant",
-        harness: h.name,
-        supported: ["non-empty, comma-free tool names"],
-        detail: `tools=${JSON.stringify(opts.tools)}`,
-      });
-    }
-    tail.push(h.launch.toolsFlag, opts.tools.join(","));
+  if (opts.tools !== undefined || opts.excludeTools !== undefined) {
+    const rendered = renderToolSelection(h, {
+      include: opts.tools,
+      exclude: opts.excludeTools,
+    });
+    tail.push(...rendered.tokens);
   }
   return tail;
 };

package/src/interpretation/hints.ts

@@ -0,0 +1,99 @@
+/**
+ * Curated refusal hints (D8), confirmed in review 2026-08-18
+ * (test/fixtures/phase0/hints-confirmed.md is the durable record). A hint
+ * is the nearest-alternative control for the CURRENT harness, shown before
+ * the cross-harness support list so a scanning caller meets the
+ * stay-on-harness suggestion first. Wording is locked verbatim; unit tests
+ * pin every string.
+ */
+import type { HarnessDescriptor } from "../knowledge/descriptor.js";
+import type { RefusalOption } from "./refusal.js";
+
+const HINTS: Readonly<Record<string, Readonly<Record<string, string>>>> = deepFreezeSafe({
+  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",
+    write:
+      "claude has no write toggle; keep the Write tool out with --tools that omits it, or --disallowedTools Write for the deny-complement spelling",
+    shell:
+      "claude has no shell toggle; disallow the Bash tool (--tools without Bash, or --disallowedTools Bash) and note Monitor can still run commands in headless runs",
+    maxSteps:
+      "claude has no step cap flag; bound the work in the prompt (task size, 'stop after N operations') or impose a wall-clock timeout at the caller",
+    provider:
+      "claude routes models through Anthropic only (Bedrock/Vertex via settings); use --model to pick within it - there is no separate provider selector",
+    "discovery.tools":
+      "claude has no tools-discovery toggle (tools are always compiled in); shape the tool set with --tools/--disallowedTools instead",
+    "discovery.instructionFiles":
+      "claude has no isolated instruction-file toggle; --setting-sources project isolates from user-level settings but also skips hooks, LSP and keychain reads - weigh that before using it as an approximation",
+  },
+  codex: {
+    write:
+      "codex has no write toggle; use --sandbox read-only (config: sandbox_mode) so shell commands cannot write either",
+    shell:
+      "codex has no shell toggle; disable the shell tool via config (-c features.shell_tool=false) or use --sandbox read-only",
+    maxSteps:
+      "codex has no step cap flag; bound via sandbox policy and a caller-side timeout, or prompt-level limits",
+    provider:
+      "codex routes models through OpenAI (or --oss for local); use --model to pick within it - there is no separate provider selector",
+    "discovery.tools":
+      "codex has no tools-discovery toggle; disable tool classes via config keys (features.shell_tool, web_search) instead",
+    "discovery.instructionFiles":
+      "codex always loads AGENTS.md hierarchy; no per-call toggle exists - keep the files out of the tree or work from a directory without them",
+    "discovery.extensions":
+      "codex loads MCP servers and plugins from config; disable per-server with -c or codex mcp remove rather than a call-time toggle",
+    "discovery.skills":
+      "codex discovers skills from its skills directory; no call-time toggle - remove or move the skill files instead",
+  },
+  pi: {
+    sandbox:
+      "pi has no sandbox dimension; approximate with a minimal tool grant (--tools read,grep,find,ls) so the run cannot write or execute, or sandbox the process yourself (container, VM)",
+    write:
+      "pi has no write toggle; grant without the write tool (--tools read,bash,edit) or use --exclude-tools write",
+    shell:
+      "pi has no shell toggle; grant without the bash tool (--tools read,edit,write) or use --exclude-tools bash",
+    maxSteps:
+      "pi has no step cap flag; bound the work in the prompt or impose a wall-clock timeout at the caller",
+  },
+  muse: {
+    sandbox:
+      "muse's sandbox is on by default and not selectable per-call; --disable-sandbox exists to turn it OFF, and exposure can be tuned with --disable-write, --disable-shell, --disable-web-tools - there is no mode selector",
+    provider:
+      "muse routes models through its own API; use --model to pick within it - there is no separate provider selector",
+    "discovery.tools":
+      "muse has no tools-discovery toggle; gate execution with --disable-write/--disable-shell/--disable-web-tools",
+    "discovery.instructionFiles":
+      "muse loads rules per workspace trust; --no-foreign-personal-context excludes foreign personal rules, and withholding --trust-workspace keeps workspace rules unloaded",
+    "discovery.skills":
+      "muse scopes skills by trust like rules; --no-foreign-personal-context drops foreign skills and untrusted workspaces stay unloaded - there is no unconditional skills-off switch",
+  },
+});
+
+/** 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];
+
+/** All hints - for the unit test that pins every string against the
+ * evidence file's count. */
+export const allHints = (): ReadonlyArray<{ harness: string; option: string; text: string }> => {
+  const out: { harness: string; option: string; text: string }[] = [];
+  for (const [harness, table] of Object.entries(HINTS)) {
+    for (const [option, text] of Object.entries(table)) out.push({ harness, option, text });
+  }
+  return out;
+};
+
+/** Convenience for raise sites that already hold the descriptor. */
+export const hintForDescriptor = (
+  h: HarnessDescriptor,
+  option: RefusalOption,
+): string | undefined => hintFor(h.name, option);