@dungle-scrubs/harness-cli-normalizer 0.5.7 → 0.6.1

package/src/cli/config.ts

@@ -20,8 +20,9 @@ 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";
-import { TOOL_SELECTOR } from "../interpretation/tool-selection.js";
-import { validateAccess } from "../interpretation/vocabulary.js";
+import { isQuestionMode, QUESTION_MODES } from "../interpretation/question.js";
+import type { ConfigTier } from "../interpretation/resolve-options.js";
+import { CLEAN_SELECTOR, validateAccess } from "../interpretation/vocabulary.js";
 import { HARNESS_NAMES } from "../knowledge/descriptor.js";
 import { defaultDescriptors } from "../knowledge/overrides.js";
 
@@ -68,6 +69,7 @@ const KNOWN_KEYS = new Set([
   "model",
   "provider",
   "sandbox",
+  "contextWindow",
   "tools",
   "excludeTools",
   "autonomy",
@@ -88,11 +90,10 @@ const KNOWN_KEYS = new Set([
 
 const LIST_KEYS = new Set(["tools", "excludeTools"]);
 const BOOL_KEYS = new Set(["autonomy", "write", "shell"]);
-const QUESTIONS_VALUES = new Set(["ask", "assume", "none"]);
 
 /** 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> => {
+export const parseUserConfig = (text: string): ConfigTier => {
   let raw: unknown;
   try {
     raw = JSON.parse(text);
@@ -126,7 +127,7 @@ export const parseUserConfig = (text: string): Partial<TurnOptions> => {
         );
       }
       const toolMapObj = value as Record<string, unknown>;
-      const SEL = TOOL_SELECTOR;
+      const SEL = CLEAN_SELECTOR;
       const descSet = defaultDescriptors();
       const harnessNames = HARNESS_NAMES as readonly string[];
       for (const [harness, inner] of Object.entries(toolMapObj)) {
@@ -228,9 +229,9 @@ export const parseUserConfig = (text: string): Partial<TurnOptions> => {
       continue;
     }
     if (key === "questions") {
-      if (typeof value !== "string" || !QUESTIONS_VALUES.has(value)) {
+      if (typeof value !== "string" || !isQuestionMode(value)) {
         throw new ConfigError(
-          `config key ${JSON.stringify(key)} must be one of ${[...QUESTIONS_VALUES].join(", ")}`,
+          `config key ${JSON.stringify(key)} must be one of ${QUESTION_MODES.join(", ")}`,
         );
       }
       (out as Record<string, unknown>).questions = value;
@@ -250,24 +251,24 @@ export const parseUserConfig = (text: string): Partial<TurnOptions> => {
     }
     (out as Record<string, unknown>)[key] = value;
   }
-  return out as Partial<TurnOptions>;
+  return out as ConfigTier;
 };
 
 /** 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 =>
+export const loadUserConfig = (): { config: ConfigTier; 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 => {
+): { config: ConfigTier; 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 => {
+const loadConfigAt = (path: string): { config: ConfigTier; path: string } | null => {
   let text: string;
   try {
     text = readFileSync(path, "utf8");

package/src/cli/exit-codes.ts

@@ -9,5 +9,3 @@ export const exitCodeForCause = (cause: ExitCause): number => {
   // All non-clean causes are failures that should be exit 1, except refusal is already handled separately
   return EXIT_FAILURE;
 };
-
-export const exitCodeForRefusal = (): number => EXIT_REFUSAL;

package/src/cli/help.ts

@@ -31,6 +31,8 @@ Options:
   --model <id>              Model id (validated per harness)
   --effort <value>          Effort level (validated per harness/model)
   --sandbox <value>         Sandbox mode (codex only)
+  --context-window <tokens> Context window (codex, integer 1-272000;
+                            launch default 272000; config: contextWindow)
   --provider <value>        Provider (pi only)
   --tools <a,b>             Tool grant allowlist - canonical names (read, write,
                             edit, shell, grep, glob, list, web-fetch,
@@ -74,7 +76,7 @@ Options:
   --no-instruction-files    Disable instructionFiles discovery facet
   --no-extensions           Disable extensions discovery facet
   --skills <a,b>            Skill allowlist (names resolved against $HCN_SKILLS_ROOT
-                            or ~/.agents/skills; pi loads, claude narrows)
+                            or ~/.agents/skills; pi loads, claude and codex narrow)
   --no-skills               Disable skills discovery facet
   --cwd <path>              Working directory for spawn
   --env KEY=VAL             Environment (repeatable; KEY= deletes)
@@ -99,7 +101,8 @@ Defaults with no flags:
   git root) > user config (~/.config/hcn/config.json) > built-in profile
   > harness default. The profile pins: effort medium, sandbox
   workspace-write (codex only; other harnesses report divergence),
-  discovery on, autonomy off, write/shell on. timeout, max-steps and
+  context window 272000 (codex only; divergence elsewhere), discovery on,
+  autonomy off, write/shell on. timeout, max-steps and
   access have no default; harness default applies (access write emits
   nothing on claude/pi/muse, --sandbox workspace-write on codex via
   profile). toolMap is config-only (no flag) - canonical -> native
@@ -132,6 +135,9 @@ Options:
                             (default: no limit)
   --provider <value>        Provider (pi only)
   --model <id>              Model for the session
+  --effort <value>          Effort level for the session spawn (validated
+                            per harness/model; no default - the harness's
+                            own effort applies without the flag)
   --resume <uuid>           Resume session id (UUID). Continues the
                             conversation where it left off. --session-id
                             is an alias (mutually exclusive with --resume).
@@ -168,6 +174,7 @@ Options:
   --model <id>              Model
   --effort <value>          Effort
   --sandbox <value>         Sandbox
+  --context-window <tokens> Context window (codex, integer 1-272000)
   --provider <value>        Provider
   --tools <a,b>             Tools - canonical names (read, write, edit,
                             shell, grep, glob, list, web-fetch,

package/src/cli/index.ts

@@ -2,10 +2,12 @@
 import { realpathSync } from "node:fs";
 import { resolve } from "node:path";
 import { pathToFileURL } from "node:url";
+import { HARNESS_NAMES } from "../knowledge/descriptor.js";
 import { TOP_LEVEL_HELP } from "./help.js";
 import { getVersion } from "./version.js";
 
-const SUPPORTED = ["claude", "codex", "pi", "muse"] as const;
+/** The one harness list, read from the descriptor vocabulary. */
+const SUPPORTED: readonly string[] = HARNESS_NAMES;
 
 // Prevent EPIPE crashes when piped to head/grep -q (e.g., hcn ls | head, hcn run --json | head)
 process.stdout.on("error", (err) => {

package/src/cli/inspect.ts

@@ -1,69 +1,63 @@
-import { redactArgv } from "../execution/stream-turn.js";
-import { buildLaunchArgv } from "../interpretation/argv.js";
 import { capabilitiesOf } from "../interpretation/capabilities.js";
-import { ArgvRefusalError } from "../interpretation/refusal.js";
-import { FloorExceededError, resolveEffectiveOptions } from "../interpretation/resolve-options.js";
 import { canonicalTable, mergeToolMaps } from "../interpretation/tool-vocabulary.js";
-import type { HarnessMode } from "../knowledge/descriptor.js";
+import { HARNESS_MODES, type HarnessMode } from "../knowledge/descriptor.js";
 import { defaultDescriptors } from "../knowledge/overrides.js";
-import { parseTurnOptions, resolvePromptAsync } from "./args.js";
+import { splitPassthrough } from "./args.js";
 import { ConfigError, loadProjectConfig, loadUserConfig } from "./config.js";
 import { EXIT_REFUSAL } from "./exit-codes.js";
-import { refusalOf, refuse } from "./refuse.js";
+import { planTurn, writePlanDiagnostics } from "./plan-turn.js";
+import { refuse } from "./refuse.js";
 import { resolveHarness } from "./resolve-harness.js";
 
-const HARNESS_MODES = ["headless-turn", "headless-session", "interactive"] as const;
-
 export const inspect = async (harnessName: string, rawArgs: string[]): Promise<void> => {
   const h = resolveHarness(harnessName);
+  const { normalized } = splitPassthrough(rawArgs);
 
-  // Check for --help
-  if (rawArgs.includes("--help") || rawArgs.includes("-h")) {
+  if (normalized.includes("--help") || normalized.includes("-h")) {
     const { INSPECT_HELP } = await import("./help.js");
     process.stdout.write(INSPECT_HELP);
     return;
   }
 
-  // Check for positional prompt injection before parse (only when --argv and no explicit prompt)
-  const { parseCommonFlags, detectPositionalPromptInjection } = await import("./args.js");
-  if (rawArgs.includes("--argv")) {
-    const injection = detectPositionalPromptInjection(rawArgs.filter((a) => a !== "--argv"));
-    if (injection) {
-      const err = new ArgvRefusalError({
-        issue: "prompt-flag-injection",
-        harness: h.name,
-        supported: ["prompt must not start with '-'"],
-        detail: `it would be parsed as a flag by ${h.bin}`,
-      });
-      process.stderr.write(`${err.message}\n`);
-      process.stderr.write(`supported: prompt must not start with '-'\n`);
-      process.exitCode = 2;
+  // --argv: the preview is the plan the run command would spawn from, so
+  // the two agree by construction (RFC-02 change 10). Refusals go through
+  // the shared refuse path like every other command's.
+  if (normalized.includes("--argv")) {
+    if (normalized.includes("--capabilities")) {
+      process.stderr.write(`--capabilities and --argv are mutually exclusive; pick one\n`);
+      process.exitCode = EXIT_REFUSAL;
+      return;
+    }
+    const outcome = await planTurn(h, rawArgs, { command: "inspect" });
+    if (outcome.kind === "refusal") {
+      refuse(outcome.refusal, false);
       return;
     }
+    writePlanDiagnostics(h, outcome.plan, "argv");
+    process.stdout.write(`${JSON.stringify(outcome.plan.redactedArgv)}\n`);
+    return;
   }
 
-  // Parse flags for inspect
+  // --capabilities path: pure capability record, no spawn, no config, no prompt
+  const { parseCommonFlags } = await import("./args.js");
   let parsed: ReturnType<typeof parseCommonFlags>;
   try {
     parsed = parseCommonFlags(rawArgs);
   } catch (err) {
     const message = err instanceof Error ? err.message : String(err);
-    process.stderr.write(`unknown flag: ${message}\n`);
-    process.stderr.write(`Run 'hcn inspect --help' for usage.\n`);
-    process.exitCode = 2;
+    refuse(
+      {
+        message: `unknown flag: ${message}`,
+        issue: "invalid-option-value",
+        trailer: ["Run 'hcn inspect --help' for usage."],
+      },
+      false,
+    );
     return;
   }
-
   const values = parsed.values as Record<string, unknown>;
-  const wantArgv = values.argv === true;
 
-  // --capabilities path: pure capability record, no spawn, no config, no prompt
   if (values.capabilities === true) {
-    if (wantArgv) {
-      process.stderr.write(`--capabilities and --argv are mutually exclusive; pick one\n`);
-      process.exitCode = EXIT_REFUSAL;
-      return;
-    }
     const mode = values.mode === undefined ? "headless-turn" : String(values.mode);
     if (!(HARNESS_MODES as readonly string[]).includes(mode)) {
       process.stderr.write(
@@ -78,247 +72,72 @@ export const inspect = async (harnessName: string, rawArgs: string[]): Promise<v
     return;
   }
 
-  // Load config once at top and reuse for both paths
-  let rawUserMap: Record<string, Record<string, string>> | undefined;
-  let rawProjectMap: Record<string, Record<string, string>> | undefined;
-  let loadedTiers: {
-    user?: import("../interpretation/argv.js").TurnOptions;
-    project?: import("../interpretation/argv.js").TurnOptions;
-  } = {};
+  // The descriptor dump, with the tool vocabulary slice the config tiers
+  // extend.
+  let userMap: ReturnType<typeof loadUserConfig> = null;
+  let projectMap: ReturnType<typeof loadProjectConfig> = null;
   try {
-    const u = loadUserConfig();
-    rawUserMap = (u?.config as { toolMap?: Record<string, Record<string, string>> } | undefined)
-      ?.toolMap;
-    if (u) loadedTiers = { ...loadedTiers, user: u.config as never };
-    const p = loadProjectConfig();
-    rawProjectMap = (p?.config as { toolMap?: Record<string, Record<string, string>> } | undefined)
-      ?.toolMap;
-    if (p) loadedTiers = { ...loadedTiers, project: p.config as never };
+    userMap = loadUserConfig();
+    projectMap = loadProjectConfig();
   } catch (e) {
     if (e instanceof ConfigError) {
-      process.stderr.write(`config error: ${(e as Error).message}\n`);
-      process.exitCode = 2;
+      refuse({ message: `config error: ${e.message}`, issue: "invalid-option-value" }, false);
       return;
     }
     throw e;
   }
-  const merged = mergeToolMaps({ user: rawUserMap, project: rawProjectMap });
-
-  if (!wantArgv) {
-    const table = canonicalTable(defaultDescriptors());
-    const slice: Record<string, unknown> = {};
-    const allCanonicalForInspect = [
-      ...new Set([...Object.keys(table), ...Object.keys(merged[h.name] ?? {})]),
-    ].sort();
-    for (const canonical of allCanonicalForInspect) {
-      const perHarness = table[canonical] as Record<string, unknown> | undefined;
-      const v = perHarness?.[h.name];
-      const mapped = merged[h.name]?.[canonical];
-      if (mapped !== undefined) {
-        slice[canonical] = { native: mapped.native, source: mapped.tier };
-      } else if (v !== undefined) {
-        const vv = v as { kind: string; native?: string; key?: string };
-        const val =
-          vv.kind === "builtin"
-            ? { native: vv.native, source: "descriptor" }
-            : { ...vv, source: "descriptor" };
-        slice[canonical] = val;
-      } else {
-        slice[canonical] = { native: null, source: "none" };
-      }
+  const merged = mergeToolMaps({
+    user: userMap?.config.toolMap,
+    project: projectMap?.config.toolMap,
+  });
+  const table = canonicalTable(defaultDescriptors());
+  const slice: Record<string, unknown> = {};
+  const allCanonicalForInspect = [
+    ...new Set([...Object.keys(table), ...Object.keys(merged[h.name] ?? {})]),
+  ].sort();
+  for (const canonical of allCanonicalForInspect) {
+    const v = table[canonical]?.[h.name];
+    const mapped = merged[h.name]?.[canonical];
+    if (mapped !== undefined) {
+      slice[canonical] = { native: mapped.native, source: mapped.tier };
+    } else if (v !== undefined) {
+      slice[canonical] =
+        v.kind === "builtin"
+          ? { native: v.native, source: "descriptor" }
+          : { ...v, source: "descriptor" };
+    } else {
+      slice[canonical] = { native: null, source: "none" };
     }
-    const out = {
-      name: h.name,
-      bin: h.bin,
-      verifiedAgainst: h.verifiedAgainst,
-      versionSource: h.versionSource,
-      launch: {
-        baseFlags: h.launch.baseFlags,
-        subcommands: h.launch.subcommands,
-        streamFlags: h.launch.streamFlags,
-        promptStyle: h.launch.promptStyle,
-        toolsFlag: h.launch.toolsFlag,
-        idFlag: h.launch.idFlag,
-      },
-      resume: h.resume,
-      sessionMode: h.sessionMode,
-      vocabulary: {
-        models: h.vocabulary.models,
-        aliases: h.vocabulary.aliases,
-        efforts: h.vocabulary.efforts,
-        effortsByModel: (h.vocabulary as { effortsByModel?: unknown }).effortsByModel,
-        extensible: h.vocabulary.extensible,
-        modelFlag: h.vocabulary.modelFlag,
-      },
-      turnOptions: h.turnOptions,
-      limitMatchers: h.limitMatchers,
-      authMatchers: h.authMatchers,
-      toolVocabulary: slice,
-    };
-    process.stdout.write(`${JSON.stringify(out, null, 2)}\n`);
-    return;
-  }
-
-  // --argv preview path: need prompt + turn options
-  const positional = parsed.positionals as string[];
-  // positional[0] would be harness already consumed, but we passed rawArgs without harness - check: caller passes remaining after harness
-  // So positionals are potential prompt positional if not using --prompt
-  const positionalPrompt = positional.length > 0 ? positional[0] : undefined;
-  if (positional.length > 1) {
-    process.stderr.write(`too many positionals for inspect --argv\n`);
-    process.exitCode = 2;
-    return;
-  }
-
-  let prompt: string;
-  let promptSource: string;
-  try {
-    const resolved = await resolvePromptAsync({
-      positionalPrompt,
-      promptFlag: values.prompt as string | undefined,
-      promptFile: values["prompt-file"] as string | undefined,
-    });
-    prompt = resolved.prompt;
-    promptSource = resolved.source;
-  } 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;
   }
-
-  // Build TurnOptions from flags
-  let turnOpts: ReturnType<typeof parseTurnOptions>;
-  try {
-    turnOpts = parseTurnOptions(values);
-  } 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;
-  }
-
-  // Mirror run.ts skills resolution (F-16): resolve names and build claude tokens
-  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, h.name);
-      const skillTokens: string[] = [];
-      if (h.name === "claude") {
-        const { claudeSkillOverridesArg } = await import("../interpretation/skills-selection.js");
-        skillTokens.push(...claudeSkillOverridesArg(listKnownSkills(), resolvedSkills));
-      } else if (h.name === "codex") {
-        const { codexSkillConfigArg } = await import("../interpretation/skills-selection.js");
-        skillTokens.push(...codexSkillConfigArg(listKnownSkills(), resolvedSkills));
-      }
-      (turnOpts as unknown as Record<string, unknown>).skills = resolvedSkills;
-      (turnOpts as unknown as Record<string, unknown>).__skillTokens = skillTokens;
-    } 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;
-    }
-  }
-
-  // Resume previews from unresolved options, mirroring run.ts launch-only rule (F-15)
-  if (values.resume !== undefined || values["session-id"] !== undefined) {
-    if (values.resume !== undefined && values["session-id"] !== undefined) {
-      const err = new ArgvRefusalError({
-        issue: "mutually-exclusive-options",
-        harness: h.name,
-        supported: ["--resume or --session-id, not both (--session-id is an alias for --resume)"],
-        detail: "both --resume and --session-id given",
-      });
-      process.stderr.write(`${err.message}\n`);
-      if (err.supported.length) process.stderr.write(`supported: ${err.supported.join(", ")}\n`);
-      process.exitCode = 2;
-      return;
-    }
-    const { buildResumeArgv } = await import("../interpretation/argv.js");
-    const resumeId = String(values.resume ?? values["session-id"]);
-    try {
-      const resumeOpts = {
-        ...(turnOpts as object),
-        prompt,
-        sessionId: resumeId,
-        ...(promptSource !== "positional" ? { __explicitPrompt: true as const } : {}),
-      } as Parameters<typeof buildResumeArgv>[1];
-      const resumeArgv = buildResumeArgv(h, resumeOpts);
-      const redactedResume = redactArgv(resumeArgv, prompt);
-      process.stdout.write(`${JSON.stringify(redactedResume)}\n`);
-      process.stderr.write(`argv: ${redactedResume.join(" ")}\n`);
-      return;
-    } 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;
-    }
-  }
-
-  // Reuse already-loaded config for argv preview
-  const tiers: {
-    user?: Partial<ReturnType<typeof parseTurnOptions>>;
-    project?: Partial<ReturnType<typeof parseTurnOptions>>;
-  } = {};
-  if (loadedTiers.user) tiers.user = loadedTiers.user as never;
-  if (loadedTiers.project) tiers.project = loadedTiers.project as never;
-  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;
-    }
-    if (resErr instanceof ArgvRefusalError) {
-      refuse(refusalOf(resErr as ArgvRefusalError), false);
-      return;
-    }
-    throw resErr;
-  }
-  const { writeProvenance } = await import("./provenance.js");
-  writeProvenance(h.name, resolved.provenance, resolved.unrenderable);
-  const { prompt: _p, ...effectiveRest } = resolved.options as { prompt: string };
-  const fullOpts = {
-    ...(effectiveRest as object),
-    prompt,
-    ...(promptSource !== "positional" ? { __explicitPrompt: true as const } : {}),
-  } as Parameters<typeof buildLaunchArgv>[1];
-
-  let argv: string[];
-  try {
-    argv = buildLaunchArgv(h, fullOpts);
-    const skillTokens = (effectiveRest as unknown as { __skillTokens?: string[] }).__skillTokens;
-    if (skillTokens !== undefined && skillTokens.length > 0) argv.push(...skillTokens);
-  } catch (err) {
-    if (err instanceof ArgvRefusalError) {
-      refuse(refusalOf(err as ArgvRefusalError), false);
-      return;
-    }
-    throw err;
-  }
-
-  // Redact prompt for display, but keep structure
-  const redacted = redactArgv(argv, prompt);
-
-  process.stdout.write(`${JSON.stringify(redacted)}\n`);
-  process.stderr.write(`argv: ${redacted.join(" ")}\n`);
+  const out = {
+    name: h.name,
+    bin: h.bin,
+    verifiedAgainst: h.verifiedAgainst,
+    versionSource: h.versionSource,
+    launch: {
+      baseFlags: h.launch.baseFlags,
+      subcommands: h.launch.subcommands,
+      streamFlags: h.launch.streamFlags,
+      promptStyle: h.launch.promptStyle,
+      toolsFlag: h.tools.includeFlag,
+      idFlag: h.launch.idFlag,
+    },
+    resume: h.resume,
+    sessionMode: h.sessionMode,
+    vocabulary: {
+      models: h.vocabulary.models,
+      aliases: h.vocabulary.aliases,
+      efforts: h.vocabulary.efforts,
+      effortsByModel: h.vocabulary.effortsByModel,
+      extensible: h.vocabulary.extensible,
+      modelFlag: h.vocabulary.modelFlag,
+    },
+    turnOptions: h.turnOptions,
+    limitMatchers: h.limitMatchers,
+    authMatchers: h.authMatchers,
+    toolVocabulary: slice,
+  };
+  process.stdout.write(`${JSON.stringify(out, null, 2)}\n`);
 };
 
 export const inspectCommand = inspect;