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

package/src/execution/stream-turn.ts

@@ -28,6 +28,7 @@ import type { FailureSummary } from "./failure.js";
 import {
   failureFromAuth,
   failureFromLimit,
+  failureFromNative,
   failureFromRejected,
   failureFromTransport,
   reduceFailures,
@@ -55,13 +56,18 @@ const SECRETISH = /(sk-[A-Za-z0-9_-]{8,}|(?:token|key|secret|password)=\S+)/i;
 
 /** Redact by POSITION, not shape: the prompt is a known argv slot and is
  * masked wholesale (content never reaches a log line - v1 D-005); every
- * other token is kept unless it is secret-shaped. */
-export const redactArgv = (argv: readonly string[], prompt?: string): string[] =>
-  argv.map((token) => {
-    if (prompt !== undefined && token === prompt) return `[prompt:${prompt.length}ch]`;
+ * other token is kept unless it is secret-shaped. Only the prompt's
+ * positional slot is masked, so a one-word prompt that equals a flag
+ * value does not cause that flag value to be masked. */
+export const redactArgv = (argv: readonly string[], prompt?: string): string[] => {
+  const promptIndex = prompt !== undefined ? argv.lastIndexOf(prompt) : -1;
+  const promptLabel = prompt !== undefined ? `[prompt:${prompt.length}ch]` : "";
+  return argv.map((token, index) => {
+    if (index === promptIndex) return promptLabel;
     if (SECRETISH.test(token)) return "[redacted]";
     return token;
   });
+};
 
 /** Bounded tail of unmatched stderr - the crash context a nonzero exit is
  * explained by (v1 kept the turn's output slice for exactly this). Shared
@@ -91,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(
@@ -139,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) {
@@ -147,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
@@ -356,8 +371,7 @@ export async function* streamTurn(
         if (auth !== null) {
           const failure = failureFromAuth(auth);
           await pushFailure(failure);
-          // Also emit error for compat? The old code emitted error, but now we emit failure.
-          // Keep error for 0.1.3 compat as well
+          // Emit error alongside failure for 0.1.3 compat
           await queue.push({ kind: "error", message: `auth wall: ${auth}` });
           continue;
         }
@@ -396,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 &&
@@ -404,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 };
@@ -427,11 +450,6 @@ export async function* streamTurn(
             : "crash";
     const reduced = reduceFailures(failures);
     if (reduced && cause === "clean") cause = "failed";
-    // Also handle pi stopReason error at exit 0 yielding failed - if we have a failure and exit 0, ensure cause is failed
-    if (reduced && exitCode === 0 && cause !== "limit" && cause !== "stall") {
-      // If we have any failure at exit 0, the cause should be failed, not clean
-      if (cause === "clean") cause = "failed";
-    }
     const tail = stderrTail.snapshot();
     log({
       event: "exit",
@@ -452,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);

package/src/interpretation/refusal.ts

@@ -17,19 +17,32 @@ export const REFUSAL_ISSUES = deepFreeze([
   "unknown-model",
   "invalid-env",
   "invalid-tool-grant",
+  "unknown-tool-name",
+  "mutually-exclusive-options",
   "prompt-flag-injection",
   "no-autonomy-mode",
   "no-session-mode",
 ] as const);
 export type RefusalIssue = (typeof REFUSAL_ISSUES)[number];
 
+/** The option a refusal names: turn-option spec keys (descriptor tables)
+ * plus the tool-list dimensions and autonomy, which render via dedicated
+ * descriptor fields rather than a spec table. Kept closed so consumers can
+ * branch on it without a default arm. */
+export type RefusalOption =
+  | TurnOptionKey
+  | "tools"
+  | "excludeTools"
+  | "autonomy"
+  | `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. */
 export const buildRefusalMessage = (
   issue: RefusalIssue,
   harness: HarnessName,
-  option?: TurnOptionKey,
+  option?: RefusalOption,
   facet?: DiscoveryFacet,
   supported: readonly string[] = [],
   detail?: string,
@@ -66,6 +79,10 @@ export const buildRefusalMessage = (
       return `invalid env key or value for ${harness}${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`;
+    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`;
+    case "mutually-exclusive-options":
+      return `${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`;
     case "no-autonomy-mode":
@@ -83,15 +100,25 @@ export const buildRefusalMessage = (
 export class ArgvRefusalError extends Error {
   readonly issue: RefusalIssue;
   readonly harness: HarnessName;
-  readonly option?: TurnOptionKey;
+  readonly option?: RefusalOption;
   readonly facet?: DiscoveryFacet;
   readonly supported: readonly string[];
+  /** D7: which harnesses DO express the refused option, native spellings
+   * included. Derived by the raise site from descriptors - absent when the
+   * refusing layer has no descriptor set in scope. */
+  readonly supportedBy?: ReadonlyArray<{ harness: string; spelling: string }>;
+  /** D8: nearest-alternative suggestion for the CURRENT harness - keeps a
+   * scanning agent on its chosen harness instead of switching. Curatorial
+   * data set at the raise site; absent when no hint exists. */
+  readonly hint?: string;
   constructor(args: {
     readonly issue: RefusalIssue;
     readonly harness: HarnessName;
-    readonly option?: TurnOptionKey;
+    readonly option?: RefusalOption;
     readonly facet?: DiscoveryFacet;
     readonly supported?: readonly string[];
+    readonly supportedBy?: ReadonlyArray<{ harness: string; spelling: string }>;
+    readonly hint?: string;
     readonly detail?: string;
     readonly message?: string;
   }) {
@@ -112,5 +139,7 @@ export class ArgvRefusalError extends Error {
     this.option = args.option;
     this.facet = args.facet;
     this.supported = args.supported ?? [];
+    this.supportedBy = args.supportedBy;
+    this.hint = args.hint;
   }
 }

package/src/interpretation/resolve-options.ts

@@ -0,0 +1,190 @@
+/**
+ * Option resolution: the precedence chain args > user config > built-in
+ * profile, plus provenance. Pure - the config FILE is read by the CLI layer
+ * and passed in as data; this layer only decides what wins.
+ *
+ * Launch-only: callers apply resolved options on launch, never resume (a
+ * resumed session keeps its session's settings - same rule the codex
+ * sandbox default already follows).
+ */
+import type { HarnessDescriptor } from "../knowledge/descriptor.js";
+import { DEFAULT_TURN_PROFILE, type ProfileKey } from "../knowledge/profile.js";
+import type { TurnOptions } from "./argv.js";
+
+export type ProvenanceTier = "arg" | "project-config" | "user-config" | "profile" | "harness";
+
+export interface ProvenanceEntry {
+  readonly key: string;
+  readonly value: unknown;
+  readonly tier: ProvenanceTier;
+}
+
+/** D5: the project floor caps arg grants; exceeding it refuses naming both
+ * sets. Structured-first: fields, not prose parsing. */
+export class FloorExceededError extends Error {
+  readonly harness: string;
+  readonly excess: readonly string[];
+  readonly floor: readonly string[];
+  constructor(harness: string, excess: readonly string[], floor: readonly string[]) {
+    super(
+      `tool grant exceeds the project floor: ${JSON.stringify(excess)} not in floor ${JSON.stringify(floor)} - request a grant within the floor or raise the floor in the project config`,
+    );
+    this.name = "FloorExceededError";
+    this.harness = harness;
+    this.excess = excess;
+    this.floor = floor;
+  }
+}
+
+export interface ResolvedOptions {
+  readonly options: TurnOptions;
+  readonly provenance: readonly ProvenanceEntry[];
+  /** Profile dimensions this harness cannot express (skip-and-report,
+   * never refuse): rendered as divergence, not failure. */
+  readonly unrenderable: readonly string[];
+}
+
+/** Expressibility per profile dimension. Dimensions whose "on" state is
+ * the harness's own default (discovery all-on) or whose "off" state emits
+ * nothing (autonomy false) are expressible EVERYWHERE - the profile value
+ * resolves to "emit nothing," which every harness can do. Divergence is
+ * reserved for dimensions that would emit a flag the harness lacks. */
+const EXPRESSIBLE: Readonly<Record<ProfileKey, (h: HarnessDescriptor) => boolean>> = {
+  effort: (h) => h.turnOptions.effort !== undefined,
+  sandbox: (h) => h.turnOptions.sandbox !== undefined,
+  discovery: () => true,
+  autonomy: () => true,
+};
+
+export interface ConfigTiers {
+  /** ~/.config/hcn/config.json (XDG) - machine-wide defaults. */
+  readonly user?: Readonly<Partial<TurnOptions>>;
+  /** <git-root>/.hcn/config.json - auto-discovered (ratified A), the ALL-
+   * OFF tier; its `tools` key is both the default grant and the FLOOR: an
+   * arg grant exceeding it refuses, naming both sets (D5). */
+  readonly project?: Readonly<Partial<TurnOptions>>;
+}
+
+/** Merge semantics (gap 1, resolved): config keys are scalars and lists in
+ * schema v1 - there is nothing to deep-merge INTO - so precedence is whole-
+ * key replacement: arg > project > user > profile. A future nested key
+ * (per-harness sections) ships with schema v2 and its own merge rule. */
+const effectiveConfig = (tiers: ConfigTiers): Readonly<Partial<TurnOptions>> => ({
+  ...(tiers.user ?? {}),
+  ...(tiers.project ?? {}),
+});
+
+/** Resolve the effective options for a LAUNCH. `args` is what the caller
+ * passed explicitly (highest tier); `userConfig` the parsed config file;
+ * the profile is the floor. Keys absent everywhere defer to the harness
+ * and are reported with tier "harness" only when something (config or
+ * profile) attempted them - a truly untouched dimension is nobody's
+ * business and appears in provenance as tier "harness" with no value. */
+/** A discovery value emits nothing when every facet is true (on). */
+const emitsNothing = (value: unknown): boolean =>
+  typeof value === "object" &&
+  value !== null &&
+  Object.values(value as Record<string, unknown>).every((v) => v === true);
+
+export const resolveEffectiveOptions = (
+  h: HarnessDescriptor,
+  args: TurnOptions,
+  tiers: ConfigTiers = {},
+): ResolvedOptions => {
+  const provenance: ProvenanceEntry[] = [];
+  const unrenderable: string[] = [];
+  const config = effectiveConfig(tiers);
+  const sourceTier = (key: string): ProvenanceTier | undefined => {
+    if (tiers.project?.[key as keyof TurnOptions] !== undefined) return "project-config";
+    if (tiers.user?.[key as keyof TurnOptions] !== undefined) return "user-config";
+    return undefined;
+  };
+
+  // D5 toolset expansion: a bare --tools name matching a configured
+  // toolset resolves to its list BEFORE the floor check, so a named set
+  // within the floor passes and one exceeding it refuses naming the set's
+  // members. Project toolsets win name collisions over user toolsets.
+  const toolsets = {
+    ...((tiers.user as { toolsets?: Record<string, string[]> } | undefined)?.toolsets ?? {}),
+    ...((tiers.project as { toolsets?: Record<string, string[]> } | undefined)?.toolsets ?? {}),
+  };
+  let effectiveArgs = args;
+  if (
+    args.tools !== undefined &&
+    args.tools.length === 1 &&
+    toolsets[args.tools[0] as string] !== undefined
+  ) {
+    effectiveArgs = { ...args, tools: toolsets[args.tools[0] as string] };
+    provenance.push({
+      key: "tools",
+      value: effectiveArgs.tools,
+      tier: "arg",
+    });
+  }
+  const resolved: Record<string, unknown> = { ...effectiveArgs };
+
+  // D5 floor: a project toolset floor caps any arg grant; exceeding it is
+  // a structured refusal naming both sets - never a silent clamp.
+  const floor = tiers.project?.tools;
+  if (floor !== undefined && effectiveArgs.tools !== undefined) {
+    const floorSet = new Set(floor);
+    const excess = effectiveArgs.tools.filter((t) => !floorSet.has(t));
+    if (excess.length > 0) {
+      throw new FloorExceededError(h.name, excess, [...floor]);
+    }
+  }
+
+  // Profile is the floor: apply only where nothing above it set the key.
+  for (const [key, value] of Object.entries(DEFAULT_TURN_PROFILE)) {
+    const argsSet = effectiveArgs[key as keyof TurnOptions] !== undefined;
+    const tier = sourceTier(key);
+    if (argsSet) {
+      provenance.push({ key, value: effectiveArgs[key as keyof TurnOptions], tier: "arg" });
+      continue;
+    }
+    if (tier !== undefined) {
+      provenance.push({ key, value: config[key as keyof TurnOptions], tier });
+      resolved[key] = config[key as keyof TurnOptions];
+      continue;
+    }
+    const expressible = EXPRESSIBLE[key as ProfileKey]?.(h) ?? false;
+    if (!expressible) {
+      // Skip-and-report: a profile default this harness cannot express is
+      // reported divergence, never a refusal and never silence.
+      unrenderable.push(key);
+      provenance.push({ key, value, tier: "harness" });
+      continue;
+    }
+    // Dimensions whose value reduces to "emit nothing" (autonomy false,
+    // discovery all-on) stay ABSENT from the resolved options - the
+    // harness's default already satisfies the profile, and emitting
+    // explicit on-flags would change resume grammar and add breakage
+    // surface for no semantic gain. Provenance still records the tier.
+    if ((key === "autonomy" && value === false) || (key === "discovery" && emitsNothing(value))) {
+      provenance.push({ key, value, tier: "profile" });
+      continue;
+    }
+    resolved[key] = value;
+    provenance.push({ key, value, tier: "profile" });
+  }
+
+  // Config keys outside the profile surface pass through at their own tier
+  // (validated later by the same renderers as args).
+  for (const [key, value] of Object.entries(config)) {
+    if (key === "toolsets") continue; // expanded into args above, never a turn option
+    if (key in DEFAULT_TURN_PROFILE) continue;
+    if (effectiveArgs[key as keyof TurnOptions] !== undefined) {
+      provenance.push({ key, value: effectiveArgs[key as keyof TurnOptions], tier: "arg" });
+      continue;
+    }
+    resolved[key] = value;
+    const tier = sourceTier(key) ?? "user-config";
+    provenance.push({ key, value, tier });
+  }
+
+  return {
+    options: resolved as unknown as TurnOptions,
+    provenance,
+    unrenderable,
+  };
+};

package/src/interpretation/store.ts

@@ -21,7 +21,7 @@ const slugFor = (h: HarnessDescriptor, cwd: string): string => {
     case "dash-separators":
       return normalized.replace(/[/.]/g, "-");
     case "pi-dash-wrapped":
-      // pi 0.84.1, verified on-disk: leading slash stripped, '/' -> '-',
+      // pi 0.84.2, verified on-disk: leading slash stripped, '/' -> '-',
       // dots preserved, wrapped in double dashes:
       // /Users/kevin/dev/x -> --Users-kevin-dev-x--
       return `--${normalized.replace(/^\//, "").replace(/\//g, "-")}--`;