kairn-cli 2.3.0 → 2.4.0

package/dist/cli.js

@@ -1,3 +1,99 @@
+var __defProp = Object.defineProperty;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __esm = (fn, res) => function __init() {
+  return fn && (res = (0, fn[__getOwnPropNames(fn)[0]])(fn = 0)), res;
+};
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+
+// src/evolve/memory.ts
+var memory_exports = {};
+__export(memory_exports, {
+  buildRunSummary: () => buildRunSummary,
+  formatMemoryForProposer: () => formatMemoryForProposer,
+  loadProposerMemory: () => loadProposerMemory,
+  saveRunSummary: () => saveRunSummary
+});
+import fs19 from "fs/promises";
+import path19 from "path";
+async function loadProposerMemory(workspacePath) {
+  const memoryPath = path19.join(workspacePath, MEMORY_FILE);
+  try {
+    const raw = await fs19.readFile(memoryPath, "utf-8");
+    const parsed = JSON.parse(raw);
+    if (Array.isArray(parsed)) return parsed;
+    return [];
+  } catch {
+    return [];
+  }
+}
+function buildRunSummary(history, baselineScore, bestScore) {
+  const effectiveMutations = [];
+  const regressiveMutations = [];
+  for (let i = 1; i < history.length; i++) {
+    const prev = history[i - 1];
+    const curr = history[i];
+    if (!curr.proposal?.mutations.length) continue;
+    const delta = curr.score - prev.score;
+    const summary = curr.proposal.mutations.map((m) => `${m.action} ${m.file}: ${m.rationale}`).join("; ");
+    if (delta > 0) {
+      effectiveMutations.push(`+${delta.toFixed(1)}: ${summary}`);
+    } else if (delta < -5) {
+      regressiveMutations.push(`${delta.toFixed(1)}: ${summary}`);
+    }
+  }
+  const improvement = bestScore - baselineScore;
+  const insights = improvement > 0 ? `Improved ${improvement.toFixed(1)} points. ${effectiveMutations.length} helpful mutations, ${regressiveMutations.length} regressions.` : `No improvement. ${regressiveMutations.length} regressions observed.`;
+  return {
+    timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+    baselineScore,
+    bestScore,
+    improvement,
+    effectiveMutations,
+    regressiveMutations,
+    insights
+  };
+}
+async function saveRunSummary(workspacePath, summary) {
+  const existing = await loadProposerMemory(workspacePath);
+  existing.push(summary);
+  const trimmed = existing.slice(-MAX_ENTRIES);
+  const memoryPath = path19.join(workspacePath, MEMORY_FILE);
+  await fs19.writeFile(memoryPath, JSON.stringify(trimmed, null, 2), "utf-8");
+}
+function formatMemoryForProposer(memory) {
+  if (memory.length === 0) return "";
+  const lines = ["## Prior Run History\n"];
+  for (const entry of memory) {
+    lines.push(`### Run at ${entry.timestamp}`);
+    lines.push(`- Baseline: ${entry.baselineScore.toFixed(1)}%, Best: ${entry.bestScore.toFixed(1)}%, Improvement: ${entry.improvement >= 0 ? "+" : ""}${entry.improvement.toFixed(1)}`);
+    if (entry.effectiveMutations.length > 0) {
+      lines.push("- Effective mutations:");
+      for (const m of entry.effectiveMutations.slice(0, 3)) {
+        lines.push(`  - ${m}`);
+      }
+    }
+    if (entry.regressiveMutations.length > 0) {
+      lines.push("- Regressive mutations (AVOID these):");
+      for (const m of entry.regressiveMutations.slice(0, 3)) {
+        lines.push(`  - ${m}`);
+      }
+    }
+    lines.push("");
+  }
+  return lines.join("\n");
+}
+var MEMORY_FILE, MAX_ENTRIES;
+var init_memory = __esm({
+  "src/evolve/memory.ts"() {
+    "use strict";
+    MEMORY_FILE = "proposer-memory.json";
+    MAX_ENTRIES = 10;
+  }
+});
+
 // src/cli.ts
 import { Command as Command12 } from "commander";
 import chalk15 from "chalk";
@@ -275,7 +371,7 @@ var ui = {
   // Key-value pairs
   kv: (key, value) => `  ${chalk.cyan(key.padEnd(14))} ${value}`,
   // File list
-  file: (path25) => chalk.dim(`    ${path25}`),
+  file: (path26) => chalk.dim(`    ${path26}`),
   // Tool display
   tool: (name, reason) => `    ${warmStone("\u25CF")} ${chalk.bold(name)}
       ${chalk.dim(reason)}`,
@@ -3782,8 +3878,8 @@ var keysCommand = new Command10("keys").description("Add or update API keys for
 import { Command as Command11 } from "commander";
 import chalk14 from "chalk";
 import ora2 from "ora";
-import fs24 from "fs/promises";
-import path24 from "path";
+import fs25 from "fs/promises";
+import path25 from "path";
 import { parse as yamlParse2 } from "yaml";
 import { confirm as confirm4, select as select4 } from "@inquirer/prompts";
 
@@ -4794,12 +4890,12 @@ async function evaluateAll(tasks, harnessPath, workspacePath, iteration, config,
 }
 
 // src/evolve/loop.ts
-import fs21 from "fs/promises";
-import path21 from "path";
+import fs22 from "fs/promises";
+import path22 from "path";
 
 // src/evolve/proposer.ts
-import fs19 from "fs/promises";
-import path19 from "path";
+import fs20 from "fs/promises";
+import path20 from "path";
 var PROPOSER_SYSTEM_PROMPT = `You are an expert agent environment optimizer. Your job is to improve a Claude Code
 agent environment (.claude/ directory) based on execution traces from real tasks.
 
@@ -4872,18 +4968,18 @@ async function readHarnessFiles(harnessPath) {
   async function walk(dir, prefix) {
     let entries;
     try {
-      entries = await fs19.readdir(dir, { withFileTypes: true });
+      entries = await fs20.readdir(dir, { withFileTypes: true });
     } catch {
       return;
     }
     for (const entry of entries) {
-      const relativePath = prefix ? path19.join(prefix, entry.name) : entry.name;
-      const fullPath = path19.join(dir, entry.name);
+      const relativePath = prefix ? path20.join(prefix, entry.name) : entry.name;
+      const fullPath = path20.join(dir, entry.name);
       if (entry.isDirectory()) {
         await walk(fullPath, relativePath);
       } else if (entry.isFile()) {
         try {
-          result[relativePath] = await fs19.readFile(fullPath, "utf-8");
+          result[relativePath] = await fs20.readFile(fullPath, "utf-8");
         } catch {
         }
       }
@@ -4899,7 +4995,7 @@ function truncateStdout(stdout, limit) {
   return `[...truncated, showing last ${limit} chars...]
 ${stdout.slice(-limit)}`;
 }
-function buildProposerUserMessage(harnessFiles, traces, tasks, history) {
+function buildProposerUserMessage(harnessFiles, traces, tasks, history, memorySection) {
   const harnessSection = ["## Current Harness Files\n"];
   const fileEntries = Object.entries(harnessFiles);
   if (fileEntries.length === 0) {
@@ -4935,7 +5031,8 @@ ${content}
   const historyBudget = remainingBudget - traceBudget;
   const traceSection = buildTraceSection(traces, traceBudget);
   const historySection = buildHistorySection(history, historyBudget);
-  return fixedContent + "\n" + traceSection + "\n" + historySection;
+  const memoryPart = memorySection ? "\n" + memorySection : "";
+  return fixedContent + "\n" + traceSection + "\n" + historySection + memoryPart;
 }
 function buildTraceSection(traces, budget) {
   if (traces.length === 0) return "## Execution Traces\n\n(No traces available)\n";
@@ -5090,7 +5187,10 @@ function parseProposerResponse(raw) {
 async function propose(iteration, workspacePath, harnessPath, history, tasks, config, proposerModel) {
   const harnessFiles = await readHarnessFiles(harnessPath);
   const traces = await loadIterationTraces(workspacePath, iteration);
-  const userMessage = buildProposerUserMessage(harnessFiles, traces, tasks, history);
+  const { loadProposerMemory: loadProposerMemory2, formatMemoryForProposer: formatMemoryForProposer2 } = await Promise.resolve().then(() => (init_memory(), memory_exports));
+  const memory = await loadProposerMemory2(workspacePath);
+  const memorySection = formatMemoryForProposer2(memory);
+  const userMessage = buildProposerUserMessage(harnessFiles, traces, tasks, history, memorySection);
   const proposerConfig = { ...config, model: proposerModel };
   const response = await callLLM(proposerConfig, userMessage, {
     systemPrompt: PROPOSER_SYSTEM_PROMPT,
@@ -5101,60 +5201,60 @@ async function propose(iteration, workspacePath, harnessPath, history, tasks, co
 }
 
 // src/evolve/mutator.ts
-import fs20 from "fs/promises";
-import path20 from "path";
+import fs21 from "fs/promises";
+import path21 from "path";
 async function applyMutations(currentHarnessPath, nextIterationDir, mutations) {
-  const newHarnessPath = path20.join(nextIterationDir, "harness");
+  const newHarnessPath = path21.join(nextIterationDir, "harness");
   await copyDir(currentHarnessPath, newHarnessPath);
   for (const mutation of mutations) {
     if (mutation.file.includes("..")) {
       continue;
     }
-    const filePath = path20.join(newHarnessPath, mutation.file);
+    const filePath = path21.join(newHarnessPath, mutation.file);
     if (mutation.action === "replace") {
       if (!mutation.oldText) {
         continue;
       }
-      const content = await fs20.readFile(filePath, "utf-8");
+      const content = await fs21.readFile(filePath, "utf-8");
       if (!content.includes(mutation.oldText)) {
         continue;
       }
-      await fs20.writeFile(
+      await fs21.writeFile(
         filePath,
         content.replace(mutation.oldText, mutation.newText),
         "utf-8"
       );
     } else if (mutation.action === "add_section") {
       try {
-        const content = await fs20.readFile(filePath, "utf-8");
-        await fs20.writeFile(
+        const content = await fs21.readFile(filePath, "utf-8");
+        await fs21.writeFile(
           filePath,
           content + "\n\n" + mutation.newText,
           "utf-8"
         );
       } catch {
-        await fs20.mkdir(path20.dirname(filePath), { recursive: true });
-        await fs20.writeFile(filePath, mutation.newText, "utf-8");
+        await fs21.mkdir(path21.dirname(filePath), { recursive: true });
+        await fs21.writeFile(filePath, mutation.newText, "utf-8");
       }
     } else if (mutation.action === "create_file") {
-      await fs20.mkdir(path20.dirname(filePath), { recursive: true });
-      await fs20.writeFile(filePath, mutation.newText, "utf-8");
+      await fs21.mkdir(path21.dirname(filePath), { recursive: true });
+      await fs21.writeFile(filePath, mutation.newText, "utf-8");
     } else if (mutation.action === "delete_section") {
       if (!mutation.oldText) {
         continue;
       }
       let sectionContent;
       try {
-        sectionContent = await fs20.readFile(filePath, "utf-8");
+        sectionContent = await fs21.readFile(filePath, "utf-8");
       } catch {
         continue;
       }
       if (!sectionContent.includes(mutation.oldText)) {
         continue;
       }
-      await fs20.writeFile(filePath, sectionContent.replace(mutation.oldText, ""), "utf-8");
+      await fs21.writeFile(filePath, sectionContent.replace(mutation.oldText, ""), "utf-8");
     } else if (mutation.action === "delete_file") {
-      await fs20.unlink(filePath).catch(() => {
+      await fs21.unlink(filePath).catch(() => {
       });
     }
   }
@@ -5202,17 +5302,17 @@ async function readAllFiles(dir) {
   async function walk(current) {
     let entries;
     try {
-      entries = await fs20.readdir(current, { withFileTypes: true });
+      entries = await fs21.readdir(current, { withFileTypes: true });
     } catch {
       return;
     }
     for (const entry of entries) {
-      const fullPath = path20.join(current, entry.name);
-      const relativePath = path20.relative(dir, fullPath);
+      const fullPath = path21.join(current, entry.name);
+      const relativePath = path21.relative(dir, fullPath);
       if (entry.isDirectory()) {
         await walk(fullPath);
       } else {
-        result[relativePath] = await fs20.readFile(fullPath, "utf-8");
+        result[relativePath] = await fs21.readFile(fullPath, "utf-8");
       }
     }
   }
@@ -5221,20 +5321,27 @@ async function readAllFiles(dir) {
 }
 
 // src/evolve/loop.ts
+function computeMutationCap(iter, maxIterations, maxMutations) {
+  if (maxIterations <= 1) return maxMutations;
+  const progress = iter / (maxIterations - 1);
+  if (progress <= 0.4) return maxMutations;
+  const decayProgress = (progress - 0.4) / 0.6;
+  return Math.max(1, Math.round(maxMutations * (1 - decayProgress * (1 - 1 / maxMutations))));
+}
 async function evolve(workspacePath, tasks, kairnConfig, evolveConfig, onProgress) {
   const history = [];
   let bestScore = -1;
   let bestIteration = 0;
   let baselineScore = 0;
   for (let iter = 0; iter < evolveConfig.maxIterations; iter++) {
-    const harnessPath = path21.join(
+    const harnessPath = path22.join(
       workspacePath,
       "iterations",
       iter.toString(),
       "harness"
     );
     try {
-      await fs21.access(harnessPath);
+      await fs22.access(harnessPath);
     } catch {
       if (iter === 0) {
         throw new Error(
@@ -5267,6 +5374,29 @@ async function evolve(workspacePath, tasks, kairnConfig, evolveConfig, onProgres
           tasksToRun.push(task);
         }
       }
+      const sampleSize = evolveConfig.evalSampleSize;
+      if (sampleSize > 0 && sampleSize < tasksToRun.length) {
+        const shuffled = [...tasksToRun].sort((a, b) => {
+          const hashA = (iter * 31 + a.id.charCodeAt(0)) % 1e3;
+          const hashB = (iter * 31 + b.id.charCodeAt(0)) % 1e3;
+          return hashA - hashB;
+        });
+        const sampled = new Set(shuffled.slice(0, sampleSize).map((t) => t.id));
+        for (const task of tasksToRun) {
+          if (!sampled.has(task.id)) {
+            const prev = prevLog.taskResults[task.id];
+            const prevVal = prev ? prev.score ?? (prev.pass ? 100 : 0) : 0;
+            carriedScores[task.id] = { pass: prevVal >= 50, score: prevVal };
+            onProgress?.({
+              type: "task-skipped",
+              iteration: iter,
+              taskId: task.id,
+              message: `Sampled out ${task.id} (mini-batch ${sampleSize}/${tasksToRun.length})`
+            });
+          }
+        }
+        tasksToRun = tasksToRun.filter((t) => sampled.has(t.id));
+      }
     }
     const { results: evalResults, aggregate: evalAggregate } = await evaluateAll(
       tasksToRun,
@@ -5327,7 +5457,7 @@ async function evolve(workspacePath, tasks, kairnConfig, evolveConfig, onProgres
       };
       await writeIterationLog(workspacePath, rollbackLog);
       history.push(rollbackLog);
-      const bestHarnessPath = path21.join(
+      const bestHarnessPath = path22.join(
         workspacePath,
         "iterations",
         bestIteration.toString(),
@@ -5345,13 +5475,14 @@ async function evolve(workspacePath, tasks, kairnConfig, evolveConfig, onProgres
             kairnConfig,
             evolveConfig.proposerModel
           );
-          if (rollbackProposal.mutations.length > evolveConfig.maxMutationsPerIteration) {
+          const rollbackCap = computeMutationCap(iter, evolveConfig.maxIterations, evolveConfig.maxMutationsPerIteration);
+          if (rollbackProposal.mutations.length > rollbackCap) {
             rollbackProposal = {
               ...rollbackProposal,
-              mutations: rollbackProposal.mutations.slice(0, evolveConfig.maxMutationsPerIteration)
+              mutations: rollbackProposal.mutations.slice(0, rollbackCap)
             };
           }
-          const nextIterDir2 = path21.join(workspacePath, "iterations", (iter + 1).toString());
+          const nextIterDir2 = path22.join(workspacePath, "iterations", (iter + 1).toString());
           await applyMutations(bestHarnessPath, nextIterDir2, rollbackProposal.mutations);
           onProgress?.({
             type: "mutations-applied",
@@ -5359,8 +5490,8 @@ async function evolve(workspacePath, tasks, kairnConfig, evolveConfig, onProgres
             mutationCount: rollbackProposal.mutations.length
           });
         } catch {
-          const nextIterDir2 = path21.join(workspacePath, "iterations", (iter + 1).toString());
-          await copyDir(bestHarnessPath, path21.join(nextIterDir2, "harness"));
+          const nextIterDir2 = path22.join(workspacePath, "iterations", (iter + 1).toString());
+          await copyDir(bestHarnessPath, path22.join(nextIterDir2, "harness"));
         }
       }
       continue;
@@ -5406,10 +5537,11 @@ async function evolve(workspacePath, tasks, kairnConfig, evolveConfig, onProgres
         kairnConfig,
         evolveConfig.proposerModel
       );
-      if (proposal.mutations.length > evolveConfig.maxMutationsPerIteration) {
+      const iterCap = computeMutationCap(iter, evolveConfig.maxIterations, evolveConfig.maxMutationsPerIteration);
+      if (proposal.mutations.length > iterCap) {
         proposal = {
           ...proposal,
-          mutations: proposal.mutations.slice(0, evolveConfig.maxMutationsPerIteration)
+          mutations: proposal.mutations.slice(0, iterCap)
         };
       }
     } catch (err) {
@@ -5419,12 +5551,12 @@ async function evolve(workspacePath, tasks, kairnConfig, evolveConfig, onProgres
         iteration: iter,
         message: `Proposer failed: ${errMsg}`
       });
-      const nextIterDir2 = path21.join(
+      const nextIterDir2 = path22.join(
         workspacePath,
         "iterations",
         (iter + 1).toString()
       );
-      await copyDir(harnessPath, path21.join(nextIterDir2, "harness"));
+      await copyDir(harnessPath, path22.join(nextIterDir2, "harness"));
       const skipLog = {
         iteration: iter,
         score: aggregate,
@@ -5437,7 +5569,7 @@ async function evolve(workspacePath, tasks, kairnConfig, evolveConfig, onProgres
       history.push(skipLog);
       continue;
     }
-    const nextIterDir = path21.join(
+    const nextIterDir = path22.join(
       workspacePath,
       "iterations",
       (iter + 1).toString()
@@ -5451,7 +5583,7 @@ async function evolve(workspacePath, tasks, kairnConfig, evolveConfig, onProgres
       );
       diffPatch = mutationResult.diffPatch;
     } catch {
-      await copyDir(harnessPath, path21.join(nextIterDir, "harness"));
+      await copyDir(harnessPath, path22.join(nextIterDir, "harness"));
     }
     onProgress?.({
       type: "mutations-applied",
@@ -5469,6 +5601,62 @@ async function evolve(workspacePath, tasks, kairnConfig, evolveConfig, onProgres
     await writeIterationLog(workspacePath, iterLog);
     history.push(iterLog);
   }
+  if (evolveConfig.usePrincipal && history.length >= 2) {
+    onProgress?.({ type: "proposing", iteration: history.length, message: "Principal Proposer synthesizing final harness" });
+    const baselineHarnessPath = path22.join(workspacePath, "iterations", "0", "harness");
+    try {
+      const principalProposal = await propose(
+        history.length,
+        workspacePath,
+        baselineHarnessPath,
+        history,
+        tasks,
+        kairnConfig,
+        evolveConfig.proposerModel
+      );
+      if (principalProposal.mutations.length > evolveConfig.maxMutationsPerIteration) {
+        principalProposal.mutations = principalProposal.mutations.slice(0, evolveConfig.maxMutationsPerIteration);
+      }
+      const principalIterNum = history.length;
+      const principalIterDir = path22.join(workspacePath, "iterations", principalIterNum.toString());
+      const mutResult = await applyMutations(baselineHarnessPath, principalIterDir, principalProposal.mutations);
+      onProgress?.({ type: "iteration-start", iteration: principalIterNum });
+      const { results: principalResults, aggregate: principalAggregate } = await evaluateAll(
+        tasks,
+        mutResult.newHarnessPath,
+        workspacePath,
+        principalIterNum,
+        kairnConfig,
+        onProgress,
+        evolveConfig.runsPerTask,
+        evolveConfig.parallelTasks
+      );
+      onProgress?.({ type: "iteration-scored", iteration: principalIterNum, score: principalAggregate });
+      const principalLog = {
+        iteration: principalIterNum,
+        score: principalAggregate,
+        taskResults: principalResults,
+        proposal: principalProposal,
+        diffPatch: mutResult.diffPatch,
+        timestamp: (/* @__PURE__ */ new Date()).toISOString()
+      };
+      await writeIterationLog(workspacePath, principalLog);
+      history.push(principalLog);
+      if (principalAggregate > bestScore) {
+        bestScore = principalAggregate;
+        bestIteration = principalIterNum;
+      }
+    } catch (err) {
+      const errMsg = err instanceof Error ? err.message : String(err);
+      onProgress?.({ type: "proposer-error", iteration: history.length, message: `Principal failed: ${errMsg}` });
+    }
+  }
+  try {
+    const { buildRunSummary: buildRunSummary2, saveRunSummary: saveRunSummary2 } = await Promise.resolve().then(() => (init_memory(), memory_exports));
+    const summary = buildRunSummary2(history, baselineScore, bestScore);
+    await saveRunSummary2(workspacePath, summary);
+  } catch {
+  }
   onProgress?.({
     type: "complete",
     iteration: history.length > 0 ? history.length - 1 : 0,
@@ -5483,8 +5671,8 @@ async function evolve(workspacePath, tasks, kairnConfig, evolveConfig, onProgres
 }
 
 // src/evolve/report.ts
-import fs22 from "fs/promises";
-import path22 from "path";
+import fs23 from "fs/promises";
+import path23 from "path";
 
 // src/evolve/diagnosis.ts
 function numericScore(s) {
@@ -5534,10 +5722,10 @@ function numericScore2(s) {
   return s.score ?? (s.pass ? 100 : 0);
 }
 async function loadAllIterations(workspacePath) {
-  const iterDir = path22.join(workspacePath, "iterations");
+  const iterDir = path23.join(workspacePath, "iterations");
   let entries;
   try {
-    entries = await fs22.readdir(iterDir);
+    entries = await fs23.readdir(iterDir);
   } catch {
     return [];
   }
@@ -5551,7 +5739,7 @@ async function loadAllIterations(workspacePath) {
 }
 async function loadTasks(workspacePath) {
   try {
-    const content = await fs22.readFile(path22.join(workspacePath, "tasks.yaml"), "utf-8");
+    const content = await fs23.readFile(path23.join(workspacePath, "tasks.yaml"), "utf-8");
     const parsed = yamlParse(content);
     return parsed?.tasks ?? [];
   } catch {
@@ -5725,13 +5913,13 @@ async function generateJsonReport(workspacePath) {
 }
 
 // src/evolve/apply.ts
-import fs23 from "fs/promises";
-import path23 from "path";
+import fs24 from "fs/promises";
+import path24 from "path";
 async function listIterations(workspacePath) {
-  const iterationsDir = path23.join(workspacePath, "iterations");
+  const iterationsDir = path24.join(workspacePath, "iterations");
   let entries;
   try {
-    entries = await fs23.readdir(iterationsDir);
+    entries = await fs24.readdir(iterationsDir);
   } catch {
     return [];
   }
@@ -5740,7 +5928,7 @@ async function listIterations(workspacePath) {
     const n = parseInt(entry, 10);
     if (!isNaN(n)) {
       try {
-        await fs23.access(path23.join(iterationsDir, entry, "harness"));
+        await fs24.access(path24.join(iterationsDir, entry, "harness"));
         nums.push(n);
       } catch {
       }
@@ -5766,16 +5954,16 @@ async function listFilesRecursive(dir) {
   async function walk(current) {
     let entries;
     try {
-      entries = await fs23.readdir(current, { withFileTypes: true });
+      entries = await fs24.readdir(current, { withFileTypes: true });
     } catch {
       return;
     }
     for (const entry of entries) {
-      const fullPath = path23.join(current, entry.name);
+      const fullPath = path24.join(current, entry.name);
       if (entry.isDirectory()) {
         await walk(fullPath);
       } else {
-        results.push(path23.relative(dir, fullPath));
+        results.push(path24.relative(dir, fullPath));
       }
     }
   }
@@ -5798,37 +5986,37 @@ async function applyEvolution(workspacePath, projectRoot, targetIteration) {
   } else {
     iter = await findBestIteration(workspacePath, iterations);
   }
-  const harnessPath = path23.join(
+  const harnessPath = path24.join(
     workspacePath,
     "iterations",
     iter.toString(),
     "harness"
   );
-  const claudeDir = path23.join(projectRoot, ".claude");
+  const claudeDir = path24.join(projectRoot, ".claude");
   const diffPreview = await generateDiff2(claudeDir, harnessPath);
   const currentFiles = await listFilesRecursive(claudeDir);
   const targetFiles = await listFilesRecursive(harnessPath);
   const allPaths = /* @__PURE__ */ new Set([...currentFiles, ...targetFiles]);
   const filesChanged = [];
   for (const filePath of allPaths) {
-    const currentContent = await fs23.readFile(path23.join(claudeDir, filePath), "utf-8").catch(() => null);
-    const targetContent = await fs23.readFile(path23.join(harnessPath, filePath), "utf-8").catch(() => null);
+    const currentContent = await fs24.readFile(path24.join(claudeDir, filePath), "utf-8").catch(() => null);
+    const targetContent = await fs24.readFile(path24.join(harnessPath, filePath), "utf-8").catch(() => null);
     if (currentContent !== targetContent) {
       filesChanged.push(filePath);
     }
   }
-  await fs23.rm(claudeDir, { recursive: true, force: true });
+  await fs24.rm(claudeDir, { recursive: true, force: true });
   await copyDir(harnessPath, claudeDir);
-  const harnessMcpJson = path23.join(harnessPath, ".mcp.json");
-  const projectMcpJson = path23.join(projectRoot, ".mcp.json");
+  const harnessMcpJson = path24.join(harnessPath, ".mcp.json");
+  const projectMcpJson = path24.join(projectRoot, ".mcp.json");
   try {
-    await fs23.access(harnessMcpJson);
-    const currentMcp = await fs23.readFile(projectMcpJson, "utf-8").catch(() => null);
-    const targetMcp = await fs23.readFile(harnessMcpJson, "utf-8").catch(() => null);
+    await fs24.access(harnessMcpJson);
+    const currentMcp = await fs24.readFile(projectMcpJson, "utf-8").catch(() => null);
+    const targetMcp = await fs24.readFile(harnessMcpJson, "utf-8").catch(() => null);
     if (currentMcp !== targetMcp) {
       filesChanged.push(".mcp.json");
     }
-    await fs23.copyFile(harnessMcpJson, projectMcpJson);
+    await fs24.copyFile(harnessMcpJson, projectMcpJson);
   } catch {
   }
   return {
@@ -5848,11 +6036,13 @@ var DEFAULT_CONFIG = {
   runsPerTask: 1,
   maxMutationsPerIteration: 3,
   pruneThreshold: 95,
-  maxTaskDrop: 20
+  maxTaskDrop: 20,
+  usePrincipal: false,
+  evalSampleSize: 0
 };
 async function loadEvolveConfigFromWorkspace(workspacePath) {
   try {
-    const configStr = await fs24.readFile(path24.join(workspacePath, "config.yaml"), "utf-8");
+    const configStr = await fs25.readFile(path25.join(workspacePath, "config.yaml"), "utf-8");
     const parsed = yamlParse2(configStr);
     return {
       model: parsed.model ?? DEFAULT_CONFIG.model,
@@ -5863,7 +6053,9 @@ async function loadEvolveConfigFromWorkspace(workspacePath) {
       runsPerTask: parsed.runs_per_task ?? DEFAULT_CONFIG.runsPerTask,
       maxMutationsPerIteration: parsed.max_mutations_per_iteration ?? DEFAULT_CONFIG.maxMutationsPerIteration,
       pruneThreshold: parsed.prune_threshold ?? DEFAULT_CONFIG.pruneThreshold,
-      maxTaskDrop: parsed.max_task_drop ?? DEFAULT_CONFIG.maxTaskDrop
+      maxTaskDrop: parsed.max_task_drop ?? DEFAULT_CONFIG.maxTaskDrop,
+      usePrincipal: parsed.use_principal ?? DEFAULT_CONFIG.usePrincipal,
+      evalSampleSize: parsed.eval_sample_size ?? DEFAULT_CONFIG.evalSampleSize
     };
   } catch {
     return { ...DEFAULT_CONFIG };
@@ -5874,9 +6066,9 @@ evolveCommand.command("init").description("Initialize an evolution workspace wit
   try {
     const projectRoot = process.cwd();
     console.log(ui.section("Evolve Init"));
-    const claudeDir = path24.join(projectRoot, ".claude");
+    const claudeDir = path25.join(projectRoot, ".claude");
     try {
-      await fs24.access(claudeDir);
+      await fs25.access(claudeDir);
     } catch {
       console.log(ui.error("No .claude/ directory found. Run kairn describe first."));
       process.exit(1);
@@ -5926,7 +6118,7 @@ evolveCommand.command("init").description("Initialize an evolution workspace wit
           if (config) {
             let claudeMd = "";
             try {
-              claudeMd = await fs24.readFile(path24.join(claudeDir, "CLAUDE.md"), "utf-8");
+              claudeMd = await fs25.readFile(path25.join(claudeDir, "CLAUDE.md"), "utf-8");
             } catch {
             }
             const profile = await buildProjectProfile(projectRoot);
@@ -5957,16 +6149,16 @@ evolveCommand.command("init").description("Initialize an evolution workspace wit
 evolveCommand.command("baseline").description("Snapshot current .claude/ directory as baseline").action(async () => {
   try {
     const projectRoot = process.cwd();
-    const workspace = path24.join(projectRoot, ".kairn-evolve");
+    const workspace = path25.join(projectRoot, ".kairn-evolve");
     console.log(ui.section("Evolve Baseline"));
     try {
-      await fs24.access(workspace);
+      await fs25.access(workspace);
     } catch {
       console.log(ui.error("No .kairn-evolve/ directory found. Run kairn evolve init first."));
       process.exit(1);
     }
     await snapshotBaseline(projectRoot, workspace);
-    const baselineDir = path24.join(workspace, "baseline");
+    const baselineDir = path25.join(workspace, "baseline");
     const fileCount = await countFiles(baselineDir);
     console.log(ui.success(`Baseline snapshot created (${fileCount} files)`));
   } catch (err) {
@@ -5975,21 +6167,21 @@ evolveCommand.command("baseline").description("Snapshot current .claude/ directo
     process.exit(1);
   }
 });
-evolveCommand.command("run").description("Run tasks against the current harness").option("--task <id>", "Run a specific task by ID").option("--iterations <n>", "Number of evolution iterations", "5").option("--runs <n>", "Run each task N times for variance measurement", "1").option("--parallel <n>", "Run up to N tasks concurrently", "1").option("--max-mutations <n>", "Max mutations per iteration", "3").option("--prune-threshold <n>", "Skip tasks scoring above this on middle iterations", "95").option("--max-task-drop <n>", "Roll back if any task drops more than N points", "20").action(async (options) => {
+evolveCommand.command("run").description("Run tasks against the current harness").option("--task <id>", "Run a specific task by ID").option("--iterations <n>", "Number of evolution iterations", "5").option("--runs <n>", "Run each task N times for variance measurement", "1").option("--parallel <n>", "Run up to N tasks concurrently", "1").option("--max-mutations <n>", "Max mutations per iteration", "3").option("--prune-threshold <n>", "Skip tasks scoring above this on middle iterations", "95").option("--max-task-drop <n>", "Roll back if any task drops more than N points", "20").option("--principal", "Run Principal Proposer as final iteration").option("--eval-sample <n>", "Sample N tasks per middle iteration (0 = all)", "0").action(async (options) => {
   try {
     const projectRoot = process.cwd();
-    const workspace = path24.join(projectRoot, ".kairn-evolve");
+    const workspace = path25.join(projectRoot, ".kairn-evolve");
     console.log(ui.section("Evolve Run"));
     try {
-      await fs24.access(workspace);
+      await fs25.access(workspace);
     } catch {
       console.log(ui.error("No .kairn-evolve/ directory found. Run kairn evolve init first."));
       process.exit(1);
     }
-    const tasksPath = path24.join(workspace, "tasks.yaml");
+    const tasksPath = path25.join(workspace, "tasks.yaml");
     let tasksContent;
     try {
-      tasksContent = await fs24.readFile(tasksPath, "utf-8");
+      tasksContent = await fs25.readFile(tasksPath, "utf-8");
     } catch {
       console.log(ui.error("No tasks.yaml found. Run kairn evolve init first."));
       process.exit(1);
@@ -6008,15 +6200,15 @@ evolveCommand.command("run").description("Run tasks against the current harness"
       console.log(ui.info(`Running ${tasksToRun.length} task(s)...`));
       console.log("");
       const config = await loadConfig();
-      const harnessPath = path24.join(projectRoot, ".claude");
+      const harnessPath = path25.join(projectRoot, ".claude");
       const results = [];
       for (const task of tasksToRun) {
-        const traceDir = path24.join(workspace, "traces", "0", task.id);
+        const traceDir = path25.join(workspace, "traces", "0", task.id);
         const spinner = ora2(`Running: ${task.id}`).start();
         const result = await runTask(task, harnessPath, traceDir, 0);
         if (config) {
-          const stdout = await fs24.readFile(path24.join(traceDir, "stdout.log"), "utf-8").catch(() => "");
-          const stderr = await fs24.readFile(path24.join(traceDir, "stderr.log"), "utf-8").catch(() => "");
+          const stdout = await fs25.readFile(path25.join(traceDir, "stdout.log"), "utf-8").catch(() => "");
+          const stderr = await fs25.readFile(path25.join(traceDir, "stderr.log"), "utf-8").catch(() => "");
           const score = await scoreTask(task, traceDir, stdout, stderr, config);
           result.score = score;
           await writeScore(traceDir, score);
@@ -6074,8 +6266,17 @@ evolveCommand.command("run").description("Run tasks against the current harness"
         process.exit(1);
       }
       evolveConfig.maxTaskDrop = maxTaskDrop;
+      if (options.principal) {
+        evolveConfig.usePrincipal = true;
+      }
+      const evalSample = parseInt(options.evalSample ?? "0", 10);
+      if (isNaN(evalSample) || evalSample < 0) {
+        console.log(ui.error("--eval-sample must be a non-negative integer"));
+        process.exit(1);
+      }
+      evolveConfig.evalSampleSize = evalSample;
       try {
-        await fs24.access(path24.join(workspace, "iterations", "0", "harness"));
+        await fs25.access(path25.join(workspace, "iterations", "0", "harness"));
       } catch {
         console.log(ui.error("No baseline harness found. Run kairn evolve baseline first."));
         process.exit(1);
@@ -6169,10 +6370,10 @@ evolveCommand.command("run").description("Run tasks against the current harness"
 evolveCommand.command("apply").description("Apply the best evolved harness to your project").option("--iter <n>", "Apply a specific iteration instead of the best").option("--force", "Apply even if git working tree is dirty").option("--no-commit", "Skip automatic git commit after applying").action(async (options) => {
   try {
     const projectRoot = process.cwd();
-    const workspace = path24.join(projectRoot, ".kairn-evolve");
+    const workspace = path25.join(projectRoot, ".kairn-evolve");
     console.log(ui.section("Evolve Apply"));
     try {
-      await fs24.access(workspace);
+      await fs25.access(workspace);
     } catch {
       console.log(ui.error("No .kairn-evolve/ directory found. Run kairn evolve init first."));
       process.exit(1);
@@ -6213,9 +6414,9 @@ evolveCommand.command("apply").description("Apply the best evolved harness to yo
 evolveCommand.command("report").description("Generate a summary report of the evolution run").option("--json", "Output machine-readable JSON instead of Markdown").action(async (options) => {
   try {
     const projectRoot = process.cwd();
-    const workspace = path24.join(projectRoot, ".kairn-evolve");
+    const workspace = path25.join(projectRoot, ".kairn-evolve");
     try {
-      await fs24.access(workspace);
+      await fs25.access(workspace);
     } catch {
       console.log(ui.error("No .kairn-evolve/ directory found. Run kairn evolve init first."));
       process.exit(1);
@@ -6236,23 +6437,23 @@ evolveCommand.command("report").description("Generate a summary report of the ev
 evolveCommand.command("diff <iter1> <iter2>").description("Show harness changes between two iterations").action(async (iter1Str, iter2Str) => {
   try {
     const projectRoot = process.cwd();
-    const workspace = path24.join(projectRoot, ".kairn-evolve");
+    const workspace = path25.join(projectRoot, ".kairn-evolve");
     const iter1 = parseInt(iter1Str, 10);
     const iter2 = parseInt(iter2Str, 10);
     if (isNaN(iter1) || isNaN(iter2)) {
       console.log(ui.error("Both arguments must be integers (iteration numbers)"));
       process.exit(1);
     }
-    const harness1 = path24.join(workspace, "iterations", iter1.toString(), "harness");
-    const harness2 = path24.join(workspace, "iterations", iter2.toString(), "harness");
+    const harness1 = path25.join(workspace, "iterations", iter1.toString(), "harness");
+    const harness2 = path25.join(workspace, "iterations", iter2.toString(), "harness");
     try {
-      await fs24.access(harness1);
+      await fs25.access(harness1);
     } catch {
       console.log(ui.error(`Iteration ${iter1} harness not found at ${harness1}`));
       process.exit(1);
     }
     try {
-      await fs24.access(harness2);
+      await fs25.access(harness2);
     } catch {
       console.log(ui.error(`Iteration ${iter2} harness not found at ${harness2}`));
       process.exit(1);
@@ -6307,10 +6508,10 @@ evolveCommand.command("diff <iter1> <iter2>").description("Show harness changes
 async function countFiles(dir) {
   let count = 0;
   try {
-    const entries = await fs24.readdir(dir, { withFileTypes: true });
+    const entries = await fs25.readdir(dir, { withFileTypes: true });
     for (const entry of entries) {
       if (entry.isDirectory()) {
-        count += await countFiles(path24.join(dir, entry.name));
+        count += await countFiles(path25.join(dir, entry.name));
       } else {
         count++;
       }