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

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,110 @@ export const run = async (harnessName: string, rawArgs: string[]): Promise<void>
   }
 
   const isExplicit = promptSource !== "positional";
+
+  // issue #38: resolve --skills names against the caller's registry root,
+  // then hand the harness its native rendering (pi loads; claude narrows).
+  const rawSkills = (turnOpts as unknown as { skills?: string[] }).skills;
+  if (rawSkills !== undefined && rawSkills.length > 0) {
+    try {
+      const { resolveSkillNames, listKnownSkills } = await import("./skills-root.js");
+      const resolvedSkills = resolveSkillNames(rawSkills);
+      const claudeTokens: string[] = [];
+      if (h.name === "claude") {
+        const { claudeSkillOverridesArg } = await import("../interpretation/skills-selection.js");
+        claudeTokens.push(...claudeSkillOverridesArg(listKnownSkills(), resolvedSkills));
+      }
+      (turnOpts as unknown as Record<string, unknown>).skills = resolvedSkills;
+      (turnOpts as unknown as Record<string, unknown>).__claudeSkillTokens = claudeTokens;
+    } catch (err) {
+      if (err instanceof ArgvRefusalError) {
+        process.stderr.write(`${err.message}\n`);
+        if (err.supported.length) process.stderr.write(`supported: ${err.supported.join(", ")}\n`);
+        process.exitCode = 2;
+        return;
+      }
+      throw err;
+    }
+  }
+
+  // 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;
+  const resolvedTiers: {
+    user?: Partial<ReturnType<typeof parseTurnOptions>>;
+    project?: Partial<ReturnType<typeof parseTurnOptions>>;
+  } = {};
+  if (extra.resume === undefined) {
+    const tiers = resolvedTiers;
+    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,16 +296,29 @@ 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);
+      const claudeSkillTokens = (effectiveTurnOpts as unknown as { __claudeSkillTokens?: string[] })
+        .__claudeSkillTokens;
+      if (claudeSkillTokens !== undefined && claudeSkillTokens.length > 0) {
+        preArgv.push(...claudeSkillTokens);
+      }
     }
     _validated = true;
   } 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;
@@ -161,7 +342,17 @@ export const run = async (harnessName: string, rawArgs: string[]): Promise<void>
   // Delete HERDR_ENV before spawn
   delete (process.env as Record<string, string | undefined>).HERDR_ENV;
 
-  const deps = nodeRunnerDeps();
+  // D11: opt-in wall-clock budget. Precedence arg > project > user (no
+  // profile entry by ratification). 0 = explicit disable.
+  const timeoutSeconds =
+    extra.timeoutSeconds !== undefined
+      ? extra.timeoutSeconds
+      : ((resolvedTiers?.project as { timeout?: number } | undefined)?.timeout ??
+        (resolvedTiers?.user as { timeout?: number } | undefined)?.timeout);
+  const deps =
+    timeoutSeconds !== undefined && timeoutSeconds > 0
+      ? nodeRunnerDeps({ turnTimeoutMs: timeoutSeconds * 1000 })
+      : nodeRunnerDeps();
 
   // Signal handling
   const _currentProc: { signal: (sig: "SIGTERM" | "SIGKILL") => void } | null = null;
@@ -234,6 +425,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/cli/skills-root.ts

@@ -0,0 +1,47 @@
+/**
+ * Skills registry resolution (issue #38): --skills names resolve against
+ * the caller's deployed root. The delegating agent's judgment picked the
+ * names; this only maps them to paths and refuses unknowns loudly -
+ * a typo silently loading nothing is the failure this prevents.
+ *
+ * Root: $HCN_SKILLS_ROOT, else ~/.agents/skills (the deployed shared
+ * registry; ~/.claude/skills symlinks to it, so claude's complement
+ * narrowing and pi's loads see the same set).
+ */
+import { existsSync, readdirSync, statSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { ArgvRefusalError } from "../interpretation/refusal.js";
+
+export const skillsRoot = (): string =>
+  process.env.HCN_SKILLS_ROOT ?? join(homedir(), ".agents", "skills");
+
+const skillDir = (root: string, name: string): string => join(root, name);
+
+export const listKnownSkills = (): string[] => {
+  const root = skillsRoot();
+  if (!existsSync(root)) return [];
+  return readdirSync(root).filter((n) => {
+    try {
+      return statSync(skillDir(root, n)).isDirectory();
+    } catch {
+      return false;
+    }
+  });
+};
+
+export const resolveSkillNames = (names: readonly string[]): string[] => {
+  const root = skillsRoot();
+  const known = new Set(listKnownSkills());
+  const unknown = names.filter((n) => !known.has(n));
+  if (unknown.length > 0) {
+    throw new ArgvRefusalError({
+      issue: "unknown-tool-name",
+      harness: "claude",
+      option: "skills",
+      supported: known.size > 0 ? [[...known].join(", ")] : ["(registry is empty)"],
+      detail: `unknown skill name(s): ${unknown.join(", ")}`,
+    });
+  }
+  return names.map((n) => skillDir(root, n));
+};

package/src/execution/failure.ts

@@ -30,6 +30,8 @@ export const FAILURE_CLASSES = Object.freeze([
   "task",
   "transport",
   "rejected",
+  "native",
+  "timeout",
 ] as const);
 export type FailureClass = (typeof FAILURE_CLASSES)[number];
 
@@ -41,13 +43,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" && cls !== "timeout";
 
 const messageFor = (cls: FailureClass, detail?: string): string => {
   switch (cls) {
@@ -67,10 +77,42 @@ 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 "timeout":
+      // D11: hcn's wall-clock budget expired and the run was killed. The
+      // caller chose this number (arg or config); retrying unchanged will
+      // hit the same wall - retry only with a raised budget.
+      return `Timeout: run exceeded its wall-clock budget and was killed (SIGTERM, then SIGKILL after grace) - raise --timeout for this workload or split the task`;
+    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})` : ""}`;
   }
-};
+}; /** D11: the run outlived its caller-set wall-clock budget. */
+export const failureFromTimeout = (): FailureSummary => ({
+  class: "timeout",
+  retryable: false,
+  message: messageFor("timeout"),
+});
+
+/** 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 +156,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 +186,11 @@ 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
+  timeout: 3,
+  // 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,7 +28,9 @@ import type { FailureSummary } from "./failure.js";
 import {
   failureFromAuth,
   failureFromLimit,
+  failureFromNative,
   failureFromRejected,
+  failureFromTimeout,
   failureFromTransport,
   reduceFailures,
 } from "./failure.js";
@@ -96,6 +98,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 +150,16 @@ 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];
+    }
+    // issue #38: claude renders the skills allowlist as settings JSON at
+    // the argv tail (the complement-off form).
+    const claudeSkillTokens = (opts as unknown as { __claudeSkillTokens?: string[] })
+      .__claudeSkillTokens;
+    if (claudeSkillTokens !== undefined && claudeSkillTokens.length > 0) {
+      argv = [...argv, ...claudeSkillTokens];
+    }
     granularity = streamingGranularityOf(h, argv);
   } catch (e) {
     if (e instanceof ArgvRefusalError) {
@@ -152,6 +168,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 +418,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,14 +431,23 @@ 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 };
     }
     // Stall watchdog also implies a transport failure if not already present
     if (killedByWatchdog && failures.length === 0) {
-      const f = failureFromTransport(`stalled: ${watchdogReason ?? "inactivity"}`);
+      // D11: a wall-clock deadline kill is a timeout, not a stall - the
+      // run was not necessarily silent, it simply outlived its budget.
+      const f =
+        watchdogReason === "turn-deadline"
+          ? failureFromTimeout()
+          : failureFromTransport(`stalled: ${watchdogReason ?? "inactivity"}`);
       failures.push(f);
       yield { kind: "failure", ...f };
     }
@@ -423,7 +455,9 @@ export async function* streamTurn(
     let cause: ExitCause = state.limitSeen
       ? "limit"
       : killedByWatchdog && exitCode !== 0
-        ? "stall"
+        ? watchdogReason === "turn-deadline"
+          ? "killed" // D11: the run was killed on budget, not stalled
+          : "stall"
         : exitCode === 0
           ? "clean"
           : exitCode === null
@@ -451,7 +485,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,12 @@
  * 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 { renderSkillsSelection } from "./skills-selection.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 +54,12 @@ export interface DiscoveryOptions {
 export interface TurnOptions {
   readonly prompt: string;
   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[];
   readonly model?: string;
   readonly autonomy?: boolean;
   readonly effort?: string;
@@ -90,32 +100,26 @@ 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);
+  }
+  if (opts.skills !== undefined && opts.skills.length > 0) {
+    tail.push(...renderSkillsSelection(h, opts.skills));
   }
   return tail;
 };