Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
29.1 KB
Raw Blame
/**
 * `gbrain skillopt <skill> [flags]` CLI dispatcher.
 *
 * Top-level command (not under `gbrain eval`) because it MUTATES files.
 * See: src/core/skillopt/ for the implementation modules.
 */

import * as path from 'node:path';
import { autoDetectSkillsDirReadOnly } from '../core/repo-root.ts';
import { runGuardedBootstrap } from '../core/skillopt/bootstrap-run.ts';
import { buildSkillOptJobData } from '../core/skillopt/job.ts';
import {
  buildModelsPlan,
  describeStrictVerdict,
  formatModelsBanner,
  resolveSkillOptModels,
  skillOptModelOpts,
  type ModelsPlanEntry,
  type StrictVerdict,
} from '../core/skillopt/models-plan.ts';
import { SKILLOPT_HELP_TEXT } from '../core/skillopt/help.ts';
import { runSkillOpt, parseSplit } from '../core/skillopt/orchestrator.ts';
import { checkpointOptimizerMode, checkpointPath, loadCheckpoint } from '../core/skillopt/checkpoint.ts';
import { noteSkillOptLoopDeprecated } from '../core/skillopt/loop-deprecation.ts';
import { formatModelsUsedTable } from '../core/budget/models-used.ts';
import { parsePositiveInt } from '../core/skillopt/output-cap.ts';
import { serializeError, StructuredAgentError } from '../core/errors.ts';
import type { BrainEngine } from '../core/engine.ts';
import type { OptimizerMode, RunReceipt, SkillOptOpts } from '../core/skillopt/types.ts';
import { capNotice, mergeCapFlag, parseCapFlag, type CapFlag } from '../core/budget/cap-flag.ts';

/** Per-run cost cap when no cap flag is passed (a `default` cap: unpriced models warn and run). */
const DEFAULT_SKILLOPT_MAX_COST_USD = 5.0;

interface ParsedFlags {
  skillName: string;
  benchmarkPath?: string;
  bootstrapFromRouting: boolean;
  bootstrapFromSkill: boolean;
  /** Number of starter tasks for --bootstrap-from-skill (default 15, cap 50). */
  bootstrapTasks?: number;
  bootstrapReviewed: boolean;
  epochs: number;
  batchSize: number;
  lr: number;
  lrSchedule: 'cosine' | 'linear' | 'constant';
  split: [number, number, number];
  optimizerModel?: string;
  targetModel?: string;
  judgeModel?: string;
  /** Optimizer output cap; beats skillopt.reflect_max_tokens config. */
  reflectMaxTokens?: number;
  /** Abort before spend unless every active model was chosen by explicit configuration. */
  modelsStrict: boolean;
  mode: 'patch' | 'rewrite';
  /** E1: `--loop` opts into the iterative reflect loop; one-shot rewrite is the default. */
  loop: boolean;
  dryRun: boolean;
  noMutate: boolean;
  allowMutateBundled: boolean;
  /** F11: optional held-out test set path. REQUIRED (non-empty) to mutate a bundled skill. */
  heldOutPath?: string;
  json: boolean;
  /** 0 = uncapped (`--max-usd off`, `--no-max-cost`, legacy `--max-cost-usd 0`). */
  maxCostUsd: number;
  /** `user` when a cap flag was passed, `default` for the $5 default (#5563). */
  maxCostSource: 'user' | 'default';
  /** The cap flag spelling the user typed, when any. */
  maxCostFlag?: string;
  maxRuntimeMin: number;
  force: boolean;
  resumeRunId?: string;
  skillsDir?: string;
  help: boolean;
  /** F4: optimize every skill under skillsDir with a benchmark. */
  all: boolean;
  /** F4: brain-wide cost cap for --all (per-skill cap stays --max-cost-usd). */
  brainWideMaxCostUsd?: number;
  /** F5: comma-separated list of target models for fleet mode. */
  targetModelsFleet?: string[];
}

export async function runSkillOptCommand(engine: BrainEngine | null, args: string[]): Promise<void> {
  if (args.length === 0 || args[0] === '--help' || args[0] === '-h') {
    process.stdout.write(SKILLOPT_HELP_TEXT);
    process.exit(0);
  }

  let parsed: ParsedFlags;
  try {
    parsed = parseFlags(args);
  } catch (err) {
    process.stderr.write(`gbrain skillopt: ${err instanceof Error ? err.message : String(err)}\n\n`);
    process.stderr.write(SKILLOPT_HELP_TEXT);
    process.exit(2);
  }

  if (parsed.help) {
    process.stdout.write(SKILLOPT_HELP_TEXT);
    process.exit(0);
  }

  if (parsed.maxCostFlag === '--max-cost-usd' && parsed.maxCostUsd === 0) {
    process.stderr.write('gbrain skillopt: --max-cost-usd 0 is deprecated; it still means uncapped, but write --max-usd off.\n');
  }
  process.stderr.write(`[skillopt] ${capNotice({ usd: parsed.maxCostUsd > 0 ? parsed.maxCostUsd : null, source: parsed.maxCostSource, flag: parsed.maxCostFlag })}\n`);

  if (!engine) {
    process.stderr.write('gbrain skillopt: requires a configured brain (engine connection failed)\n');
    process.exit(2);
  }

  // Resolve skills dir.
  const detected = autoDetectSkillsDirReadOnly(process.cwd());
  const skillsDir = parsed.skillsDir ?? detected.dir;
  if (!skillsDir) {
    process.stderr.write(`gbrain skillopt: cannot find skills directory. Pass --skills-dir <path> or run from a workspace with a skills/ directory.\n`);
    process.exit(2);
  }

  // Resolve the three roles once (flag > role config chain), with provenance.
  const modelFlags = { optimizerModel: parsed.optimizerModel, targetModel: parsed.targetModel, judgeModel: parsed.judgeModel };
  const models = await resolveSkillOptModels(engine, modelFlags);
  const { optimizerModel, targetModel, judgeModel } = skillOptModelOpts(models);

  // ── Bootstrap modes (short-circuit before the optimization loop) ────────
  // --bootstrap-from-skill reads SKILL.md directly (no routing-eval needed)
  // and emits a full starter benchmark; --bootstrap-from-routing makes one
  // call per routing intent. Both write the D15 sentinel, run under the
  // --max-cost-usd tracker and honor --models-strict / --dry-run. Provider
  // errors propagate so the user sees the real failure instead of "0 tasks".
  if (parsed.bootstrapFromRouting || parsed.bootstrapFromSkill) {
    try {
      const run = await runGuardedBootstrap({
        engine,
        mode: parsed.bootstrapFromRouting ? 'routing' : 'skill',
        skillsDir,
        skillName: parsed.skillName,
        optimizer: models.optimizer,
        taskCount: parsed.bootstrapTasks ?? 15,
        force: parsed.force,
        dryRun: parsed.dryRun,
        modelsStrict: parsed.modelsStrict,
        maxCostUsd: parsed.maxCostUsd,
        maxCostSource: parsed.maxCostSource,
      });
      if (run.dry_run) exitDryRun(run.models_plan, run.strict, parsed.json, {});
      if (parsed.json) {
        process.stdout.write(JSON.stringify({ ok: true, ...run.result, cost_usd: run.cost_usd, models_plan: run.models_plan }) + '\n');
      }
      process.exit(0);
    } catch (err) {
      handleErrorAndExit(err, parsed.json, 2);
    }
  }

  // E1: one-shot rewrite unless --loop. A resume continues in the mode its
  // checkpoint ran (a checkpoint from before this default ran the loop).
  const resumed = parsed.resumeRunId && parsed.skillName ? loadCheckpoint(skillsDir, parsed.skillName, parsed.resumeRunId) : null;
  const optimizerMode: OptimizerMode = parsed.loop ? 'reflect' : resumed ? checkpointOptimizerMode(resumed) : 'one-shot-rewrite';
  noteSkillOptLoopDeprecated(optimizerMode);

  // ── F4: --all batch mode ────────────────────────────────────────────────
  if (parsed.all) {
    try {
      const { runBatchAll } = await import('../core/skillopt/batch.ts');
      const basePlan = await buildModelsPlan(engine, models);
      process.stderr.write(formatModelsBanner(basePlan));
      const result = await runBatchAll({
        engine,
        skillsDir,
        perSkillMaxCostUsd: parsed.maxCostUsd,
        maxCostSource: parsed.maxCostSource === 'user' || parsed.brainWideMaxCostUsd !== undefined ? 'user' : 'default',
        brainWideMaxCostUsd: parsed.brainWideMaxCostUsd ?? 10.0,
        optimizerModel,
        targetModel,
        judgeModel,
        models,
        modelsStrict: parsed.modelsStrict,
        modelsBannerBaseline: basePlan,
        ...(parsed.reflectMaxTokens !== undefined ? { reflectMaxTokens: parsed.reflectMaxTokens } : {}),
        epochs: parsed.epochs,
        batchSize: parsed.batchSize,
        lr: parsed.lr,
        lrSchedule: parsed.lrSchedule,
        split: parsed.split,
        optimizerMode,
        dryRun: parsed.dryRun,
        noMutate: parsed.noMutate,
        allowMutateBundled: parsed.allowMutateBundled,
        force: parsed.force,
      });
      if (parsed.json) {
        process.stdout.write(JSON.stringify({ schema_version: 1, ...result }) + '\n');
      } else {
        process.stderr.write(`[skillopt --all] Scanned ${result.skills_scanned} skills, ran ${result.skills_run}\n`);
        process.stderr.write(`[skillopt --all] Accepted: ${result.accepted}, no_improvement: ${result.no_improvement}, errored: ${result.errored}\n`);
        process.stderr.write(`[skillopt --all] Total cost: $${result.cumulative_cost_usd.toFixed(2)} (cap $${(parsed.brainWideMaxCostUsd ?? 10).toFixed(2)})\n`);
      }
      // Exit code: 0 if at least one accepted, 1 if scanned but none accepted, 2 if errored.
      const exitCode = result.errored > 0 && result.accepted === 0 ? 2
        : result.accepted === 0 ? 1
        : 0;
      process.exit(exitCode);
    } catch (err) {
      handleErrorAndExit(err, parsed.json, 2);
    }
  }

  // ── F5: --target-models fleet mode ──────────────────────────────────────
  if (parsed.targetModelsFleet) {
    try {
      const benchmarkPath = parsed.benchmarkPath ??
        path.join(skillsDir, parsed.skillName, 'skillopt-benchmark.jsonl');
      const { runFleet } = await import('../core/skillopt/batch.ts');
      const result = await runFleet({
        engine,
        skillName: parsed.skillName,
        skillsDir,
        benchmarkPath,
        targetModels: parsed.targetModelsFleet,
        optimizerModel,
        judgeModel,
        models: { optimizer: models.optimizer, judge: models.judge },
        modelsStrict: parsed.modelsStrict,
        ...(parsed.reflectMaxTokens !== undefined ? { reflectMaxTokens: parsed.reflectMaxTokens } : {}),
        epochs: parsed.epochs,
        batchSize: parsed.batchSize,
        lr: parsed.lr,
        lrSchedule: parsed.lrSchedule,
        split: parsed.split,
        optimizerMode,
        dryRun: parsed.dryRun,
        noMutate: parsed.noMutate,
        allowMutateBundled: parsed.allowMutateBundled,
        bootstrapReviewed: parsed.bootstrapReviewed,
        ...(parsed.heldOutPath ? { heldOutPath: parsed.heldOutPath } : {}),
        maxCostUsd: parsed.maxCostUsd,
        maxCostSource: parsed.maxCostSource,
        maxRuntimeMin: parsed.maxRuntimeMin,
        force: parsed.force,
      });
      if (parsed.json) {
        process.stdout.write(JSON.stringify({ schema_version: 1, ...result }) + '\n');
      } else {
        process.stderr.write(`[skillopt fleet] Per-model scores for '${parsed.skillName}':\n`);
        for (const p of result.per_model) {
          process.stderr.write(`  ${p.target_model}: outcome=${p.outcome} score=${p.best_sel_score.toFixed(3)} cost=$${p.final_cost_usd.toFixed(2)}\n`);
        }
        if (result.best_model) {
          process.stderr.write(`[skillopt fleet] Best model: ${result.best_model} (score ${result.best_score?.toFixed(3) ?? '0'})\n`);
        }
      }
      process.exit(result.best_model ? 0 : 1);
    } catch (err) {
      handleErrorAndExit(err, parsed.json, 2);
    }
  }

  // Build benchmark path.
  const benchmarkPath = parsed.benchmarkPath ??
    path.join(skillsDir, parsed.skillName, 'skillopt-benchmark.jsonl');

  // ── F7: --background submit to Minion queue ─────────────────────────────
  // skillopt is in PROTECTED_JOB_NAMES, so we can't use the generic
  // maybeBackground helper (which doesn't pass allowProtectedSubmit). Inline
  // a small submit that does. Behavior mirrors maybeBackground: writes
  // `job_id=N` to stdout, exits 0; `--follow` execs `gbrain jobs follow`.
  if (args.includes('--background')) {
    if (engine.kind === 'pglite') {
      process.stderr.write('[--background] PGLite has no worker daemon; running inline.\n');
    } else {
      try {
        const { MinionQueue } = await import('../core/minions/queue.ts');
        const queue = new MinionQueue(engine);
        const jobData = buildSkillOptJobData({
          skillsDir,
          skillName: parsed.skillName,
          benchmarkPath,
          epochs: parsed.epochs,
          batchSize: parsed.batchSize,
          lr: parsed.lr,
          lrSchedule: parsed.lrSchedule,
          split: parsed.split,
          models,
          modelFlags,
          modelsStrict: parsed.modelsStrict,
          ...(parsed.reflectMaxTokens !== undefined ? { reflectMaxTokens: parsed.reflectMaxTokens } : {}),
          mode: parsed.mode,
          optimizerMode,
          dryRun: parsed.dryRun,
          noMutate: parsed.noMutate,
          allowMutateBundled: parsed.allowMutateBundled,
          ...(parsed.heldOutPath ? { heldOutPath: parsed.heldOutPath } : {}),
          bootstrapReviewed: parsed.bootstrapReviewed,
          maxCostUsd: parsed.maxCostUsd,
          maxCostSource: parsed.maxCostSource,
          maxRuntimeMin: parsed.maxRuntimeMin,
          force: parsed.force,
        });
        const job = await queue.add('skillopt', jobData, {
          queue: 'default',
          idempotency_key: `cli:skillopt:${parsed.skillName}`,
          max_attempts: 1,
        }, { allowProtectedSubmit: true });
        process.stdout.write(`job_id=${job.id}\n`);
        if (args.includes('--follow')) {
          const { spawn } = await import('../core/spawn.ts');
          const cmd = process.argv[0] ?? 'bun';
          const script = process.argv[1] ?? '';
          const child = spawn(cmd, [script, 'jobs', 'follow', String(job.id)], { stdio: 'inherit' });
          await new Promise<void>((resolve) => child.on('exit', () => resolve()));
        }
        process.exit(0);
      } catch (err) {
        handleErrorAndExit(err, parsed.json, 2);
      }
    }
  }

  // Build SkillOptOpts.
  const opts: SkillOptOpts = {
    engine,
    skillName: parsed.skillName,
    skillsDir,
    benchmarkPath,
    epochs: parsed.epochs,
    batchSize: parsed.batchSize,
    lr: parsed.lr,
    lrSchedule: parsed.lrSchedule,
    split: parsed.split,
    ...skillOptModelOpts(models),
    modelsStrict: parsed.modelsStrict,
    ...(parsed.reflectMaxTokens !== undefined ? { reflectMaxTokens: parsed.reflectMaxTokens } : {}),
    mode: parsed.mode,
    optimizerMode,
    dryRun: parsed.dryRun,
    noMutate: parsed.noMutate,
    allowMutateBundled: parsed.allowMutateBundled,
    ...(parsed.heldOutPath ? { heldOutPath: parsed.heldOutPath } : {}),
    bootstrapReviewed: parsed.bootstrapReviewed,
    json: parsed.json,
    maxCostUsd: parsed.maxCostUsd,
    maxCostSource: parsed.maxCostSource,
    maxRuntimeMin: parsed.maxRuntimeMin,
    force: parsed.force,
    ...(parsed.resumeRunId ? { resumeRunId: parsed.resumeRunId } : {}),
  };

  try {
    const result = await runSkillOpt(opts);
    if (parsed.dryRun) {
      exitDryRun(result.receipt.models_plan ?? [], result.receipt.models_strict!, parsed.json, { receipt: result.receipt });
    }
    if (parsed.json) {
      process.stdout.write(JSON.stringify({
        schema_version: 1,
        outcome: result.outcome,
        receipt: result.receipt,
        mutated_skill_file: result.mutatedSkillFile,
        ...(result.proposedPath ? { proposed_path: result.proposedPath } : {}),
      }) + '\n');
    } else {
      process.stderr.write(formatRunSummary(result.outcome, result.receipt, skillsDir));
      process.stderr.write(`[skillopt] Best sel-score: ${(result.receipt.best_sel_score ?? 0).toFixed(3)}\n`);
      process.stderr.write(`[skillopt] Final cost: $${(result.receipt.final_cost_usd ?? 0).toFixed(2)}\n`);
      if (result.mutatedSkillFile) {
        process.stderr.write(`[skillopt] SKILL.md rewritten with ${result.receipt.total_steps ?? 0} optimization steps.\n`);
      } else if (result.proposedPath) {
        process.stderr.write(`[skillopt] Proposed improvements written to ${result.proposedPath}. Review + copy manually.\n`);
      }
    }
    // Exit codes: 0 accepted, 1 no improvement, 2 aborted or errored.
    const exitMap = { accepted: 0, no_improvement: 1, aborted: 2, errored: 2 };
    process.exit(exitMap[result.outcome]);
  } catch (err) {
    handleErrorAndExit(err, parsed.json, 2);
  }
}

type RunSkillOptOutcome = NonNullable<RunReceipt['outcome']>;

/**
 * `--dry-run` exit: the models plan (banner already printed) and the strict
 * verdict, zero model calls. Exit 1 only when strict mode is on and fails.
 */
function exitDryRun(plan: ModelsPlanEntry[], strict: StrictVerdict, json: boolean, extra: Record<string, unknown>): never {
  if (json) {
    process.stdout.write(JSON.stringify({ schema_version: 1, dry_run: true, models_plan: plan, strict, ...extra }) + '\n');
  } else {
    process.stderr.write(`[skillopt] Dry run: no model calls made.\n${describeStrictVerdict(strict)}\n`);
    if (!strict.ok && !strict.enabled) {
      process.stderr.write('(strict mode is off; --models-strict or skillopt.models_strict would abort this run)\n');
    }
  }
  process.exit(strict.enabled && !strict.ok ? 1 : 0);
}

/**
 * Outcome + diagnostics block for the stderr summary. #3516: never a silent
 * failure — say WHY the run aborted/errored. #5584: optimizer-reply errors
 * warn even on a successful run; a retained checkpoint prints the run id,
 * its location and the exact resume command. Exported for unit tests.
 */
export function formatRunSummary(outcome: RunSkillOptOutcome, receipt: RunReceipt, skillsDir: string): string {
  const lines = [`[skillopt] Outcome: ${outcome}`];
  if (outcome === 'aborted' || outcome === 'errored') {
    const detail = receipt.abort_detail ?? '(no detail captured)';
    lines.push(`[skillopt] Failure reason: ${receipt.abort_reason ?? 'unknown'}`);
    lines.push(`[skillopt] Detail: ${detail}`);
    if (receipt.no_pricing) {
      lines.push(`[skillopt] Hint: ${receipt.no_pricing.lookup} Register it with: ${receipt.no_pricing.register_command} — then retry; or pass --no-max-cost (or --max-cost-usd 0) to run uncapped with a warn-once.`);
    } else if (detail.includes('no_pricing')) {
      lines.push(`[skillopt] Hint: gbrain has no price for the model, so the cap can't be enforced. Look up its per-token price and register it with \`gbrain pricing set\` (see the detail above), then retry; or pass --no-max-cost (or --max-cost-usd 0) to run uncapped with a warn-once.`);
    }
  }
  if (receipt.stop_reason === 'early_stop_unusable_output') {
    lines.push(`[skillopt] Stopped early: optimizer output was unusable for consecutive steps; remaining budget not spent.`);
  }
  const errors = receipt.reflect_errors ?? [];
  if (errors.length > 0) {
    lines.push(`[skillopt] Warning: ${errors.length} optimizer reply error(s) (optimizer output cap ${receipt.reflect_max_tokens ?? 'default'}); first: ${errors[0]}`);
  }
  if (receipt.skill_body_truncated) {
    lines.push(`[skillopt] Warning: skill body truncated for the optimizer (sent ${receipt.skill_body_truncated.sent_chars} of ${receipt.skill_body_truncated.total_chars} chars).`);
  }
  const modelsUsed = receipt.models_used ?? [];
  if (modelsUsed.length > 0) {
    const scope = receipt.models_used_scope === 'since_resume' ? 'since resume; earlier segments predate the ledger' : 'full run';
    lines.push(`[skillopt] Models called (${scope}; a call is one gateway operation, internal retries count once; ~ = estimated cost):`);
    for (const row of formatModelsUsedTable(modelsUsed)) lines.push(`[skillopt]   ${row}`);
  }
  for (const r of receipt.remediation ?? []) {
    lines.push(`[skillopt] Fix (${r.code}): ${r.fix} See ${r.docs}`);
  }
  if (receipt.resume_command) {
    lines.push(`[skillopt] Run id: ${receipt.run_id}`);
    lines.push(`[skillopt] Checkpoint: ${checkpointPath(skillsDir, receipt.skill, receipt.run_id)}`);
    lines.push(`[skillopt] Resume: ${receipt.resume_command}`);
  }
  return lines.join('\n') + '\n';
}

/** Exported for unit tests (CLI flag parsing, --bootstrap-tasks cap, mutual exclusion). */
export function parseFlags(args: string[]): ParsedFlags {
  let skillName = '';
  let benchmarkPath: string | undefined;
  let bootstrapFromRouting = false;
  let bootstrapFromSkill = false;
  let bootstrapTasks: number | undefined;
  let bootstrapReviewed = false;
  let epochs = 4;
  let batchSize = 8;
  let lr = 4;
  let lrSchedule: 'cosine' | 'linear' | 'constant' = 'cosine';
  let splitStr = '4:1:5';
  let optimizerModel: string | undefined;
  let modelsStrict = false;
  let targetModel: string | undefined;
  let judgeModel: string | undefined;
  let reflectMaxTokens: number | undefined;
  let mode: 'patch' | 'rewrite' = 'patch';
  let loop = false;
  let dryRun = false;
  let noMutate = false;
  let allowMutateBundled = false;
  let heldOutPath: string | undefined;
  let json = false;
  let cap: CapFlag | undefined;
  let maxRuntimeMin = 30;
  let force = false;
  let resumeRunId: string | undefined;
  let skillsDir: string | undefined;
  let help = false;
  let all = false;
  let brainWideMaxCostUsd: number | undefined;
  let targetModelsFleet: string[] | undefined;

  let i = 0;
  while (i < args.length) {
    const a = args[i]!;
    if (a === '--help' || a === '-h') { help = true; i += 1; continue; }
    if (a === '--benchmark') { benchmarkPath = args[++i]; i += 1; continue; }
    if (a === '--bootstrap-from-routing') { bootstrapFromRouting = true; i += 1; continue; }
    if (a === '--bootstrap-from-skill') { bootstrapFromSkill = true; i += 1; continue; }
    if (a === '--bootstrap-tasks') {
      const n = mustInt(args[++i], '--bootstrap-tasks');
      if (n > 50) throw new Error(`--bootstrap-tasks max is 50 (got ${n})`);
      bootstrapTasks = n;
      i += 1; continue;
    }
    if (a === '--bootstrap-reviewed') { bootstrapReviewed = true; i += 1; continue; }
    if (a === '--epochs') { epochs = mustInt(args[++i], '--epochs'); i += 1; continue; }
    if (a === '--batch-size') { batchSize = mustInt(args[++i], '--batch-size'); i += 1; continue; }
    if (a === '--lr') { lr = mustInt(args[++i], '--lr'); i += 1; continue; }
    if (a === '--lr-schedule') {
      const v = args[++i];
      if (v !== 'cosine' && v !== 'linear' && v !== 'constant') {
        throw new Error(`--lr-schedule must be cosine|linear|constant (got '${v}')`);
      }
      lrSchedule = v;
      i += 1; continue;
    }
    if (a === '--split') { splitStr = args[++i]!; i += 1; continue; }
    if (a === '--optimizer-model') { optimizerModel = args[++i]; i += 1; continue; }
    if (a === '--models-strict') { modelsStrict = true; i += 1; continue; }
    if (a === '--target-model') { targetModel = args[++i]; i += 1; continue; }
    if (a === '--judge-model') { judgeModel = args[++i]; i += 1; continue; }
    if (a === '--reflect-max-tokens') {
      const v = args[++i];
      reflectMaxTokens = parsePositiveInt(v);
      if (reflectMaxTokens === undefined) throw new Error(`--reflect-max-tokens requires a positive integer (got '${v}')`);
      i += 1; continue;
    }
    if (a === '--patch') { mode = 'patch'; i += 1; continue; }
    if (a === '--rewrite') { mode = 'rewrite'; i += 1; continue; }
    if (a === '--loop') { loop = true; i += 1; continue; }
    if (a === '--dry-run') { dryRun = true; i += 1; continue; }
    if (a === '--no-mutate') { noMutate = true; i += 1; continue; }
    if (a === '--allow-mutate-bundled') { allowMutateBundled = true; i += 1; continue; }
    if (a === '--held-out') { heldOutPath = args[++i]; i += 1; continue; }
    if (a === '--json') { json = true; i += 1; continue; }
    // D19: one shared parser. `--max-usd N|off` is canonical; the legacy
    // `--max-cost-usd` keeps #3516's meaning for 0 (uncapped) and
    // `--no-max-cost` is `--max-usd off`. Disagreeing cap flags are refused.
    if (a === '--max-usd') { cap = mergeCapFlag(cap, parseCapFlag(a, args[++i])); i += 1; continue; }
    if (a === '--max-cost-usd') { cap = mergeCapFlag(cap, parseCapFlag(a, args[++i], { zero: 'off' })); i += 1; continue; }
    if (a === '--no-max-cost') { cap = mergeCapFlag(cap, { flag: a, usd: null }); i += 1; continue; }
    if (a === '--max-runtime-min') { maxRuntimeMin = mustInt(args[++i], '--max-runtime-min'); i += 1; continue; }
    if (a === '--force') { force = true; i += 1; continue; }
    if (a === '--resume') { resumeRunId = args[++i]; i += 1; continue; }
    if (a === '--skills-dir') { skillsDir = args[++i]; i += 1; continue; }
    if (a === '--all') { all = true; i += 1; continue; }
    if (a === '--brain-wide-max-cost-usd') { brainWideMaxCostUsd = mustFloat(args[++i], '--brain-wide-max-cost-usd'); i += 1; continue; }
    if (a === '--target-models') {
      // F5: comma-separated list. Mutually exclusive with --target-model
      // (single). Triggers fleet mode.
      const v = args[++i];
      if (!v) throw new Error(`--target-models requires a comma-separated list`);
      targetModelsFleet = v.split(',').map((s) => s.trim()).filter(Boolean);
      if (targetModelsFleet.length === 0) throw new Error(`--target-models cannot be empty`);
      i += 1; continue;
    }
    if (a.startsWith('--')) { throw new Error(`unknown flag '${a}'`); }
    if (!skillName) { skillName = a; i += 1; continue; }
    throw new Error(`unexpected positional '${a}'`);
  }

  // --all does NOT require a skill name (it iterates over all skills).
  if (!all && !skillName) throw new Error('skill name is required (positional arg), or use --all for batch mode');
  // Mutual-exclusion check: --benchmark and --bootstrap-from-routing.
  if (benchmarkPath && bootstrapFromRouting) {
    throw new Error(`--benchmark and --bootstrap-from-routing are mutually exclusive`);
  }
  // --all forbids per-skill bootstrap (use the standalone bootstrap path
  // per skill instead).
  if (all && bootstrapFromRouting) {
    throw new Error(`--all and --bootstrap-from-routing are mutually exclusive (run bootstrap per skill)`);
  }
  // --bootstrap-from-skill is a standalone short-circuit: it cannot combine with
  // the other-source / multi-run flags. (--background / --follow are already
  // rejected by the unknown-flag guard since parseFlags doesn't parse them.)
  if (bootstrapFromSkill) {
    if (bootstrapFromRouting) throw new Error(`--bootstrap-from-skill and --bootstrap-from-routing are mutually exclusive`);
    if (benchmarkPath) throw new Error(`--bootstrap-from-skill and --benchmark are mutually exclusive`);
    if (all) throw new Error(`--bootstrap-from-skill and --all are mutually exclusive (run bootstrap per skill)`);
    if (targetModelsFleet) throw new Error(`--bootstrap-from-skill and --target-models are mutually exclusive`);
    if (resumeRunId) throw new Error(`--bootstrap-from-skill and --resume are mutually exclusive`);
  }
  // --bootstrap-tasks only applies to --bootstrap-from-skill.
  if (bootstrapTasks !== undefined && !bootstrapFromSkill) {
    throw new Error(`--bootstrap-tasks requires --bootstrap-from-skill`);
  }
  // --target-models and --target-model are mutually exclusive.
  if (targetModelsFleet && targetModel) {
    throw new Error(`--target-models and --target-model are mutually exclusive`);
  }
  // --target-models + --all is not yet supported (would multiply N×M runs;
  // file as v0.42 follow-up if needed).
  if (targetModelsFleet && all) {
    throw new Error(`--target-models and --all are mutually exclusive in v1`);
  }

  return {
    skillName,
    ...(benchmarkPath !== undefined ? { benchmarkPath } : {}),
    bootstrapFromRouting,
    bootstrapFromSkill,
    ...(bootstrapTasks !== undefined ? { bootstrapTasks } : {}),
    bootstrapReviewed,
    epochs,
    batchSize,
    lr,
    lrSchedule,
    split: parseSplit(splitStr),
    ...(optimizerModel !== undefined ? { optimizerModel } : {}),
    ...(targetModel !== undefined ? { targetModel } : {}),
    ...(judgeModel !== undefined ? { judgeModel } : {}),
    ...(reflectMaxTokens !== undefined ? { reflectMaxTokens } : {}),
    modelsStrict,
    mode,
    loop,
    dryRun,
    noMutate,
    allowMutateBundled,
    ...(heldOutPath !== undefined ? { heldOutPath } : {}),
    json,
    maxCostUsd: cap === undefined ? DEFAULT_SKILLOPT_MAX_COST_USD : cap.usd ?? 0,
    maxCostSource: cap === undefined ? 'default' : 'user',
    ...(cap ? { maxCostFlag: cap.flag } : {}),
    maxRuntimeMin,
    force,
    ...(resumeRunId !== undefined ? { resumeRunId } : {}),
    ...(skillsDir !== undefined ? { skillsDir } : {}),
    help,
    all,
    ...(brainWideMaxCostUsd !== undefined ? { brainWideMaxCostUsd } : {}),
    ...(targetModelsFleet !== undefined ? { targetModelsFleet } : {}),
  };
}

function mustInt(v: string | undefined, flag: string): number {
  const n = Number(v);
  if (!Number.isFinite(n) || !Number.isInteger(n) || n <= 0) {
    throw new Error(`${flag} requires a positive integer (got '${v}')`);
  }
  return n;
}

function mustFloat(v: string | undefined, flag: string): number {
  const n = Number(v);
  if (!Number.isFinite(n) || n <= 0) {
    throw new Error(`${flag} requires a positive number (got '${v}')`);
  }
  return n;
}


function handleErrorAndExit(err: unknown, json: boolean, exitCode: number): never {
  if (json) {
    const envelope = err instanceof StructuredAgentError ? err.envelope : serializeError(err);
    process.stderr.write(JSON.stringify({ ok: false, error: envelope }) + '\n');
  } else {
    process.stderr.write(`gbrain skillopt: ${err instanceof Error ? err.message : String(err)}\n`);
    if (err instanceof StructuredAgentError && err.envelope.hint) {
      process.stderr.write(`  hint: ${err.envelope.hint}\n`);
    }
  }
  process.exit(exitCode);
}