nexus-agents 2.133.0 → 2.134.0

package/dist/cli.js

@@ -13,17 +13,17 @@ import {
   generateSummary,
   parseFindings,
   sumFindings
-} from "./chunk-FKTLAPXJ.js";
-import "./chunk-RLYXX3FQ.js";
+} from "./chunk-OCKZ6F5O.js";
+import "./chunk-6LMZ7HFU.js";
 import {
   buildOpenAICompatAdapters,
   readOpenAICompatEnv
-} from "./chunk-27DRQWON.js";
+} from "./chunk-BTYYZ6VU.js";
 import {
   setupCommandAsync,
   verifyCommand
-} from "./chunk-DETYVPZO.js";
-import "./chunk-QLRH6KOT.js";
+} from "./chunk-IWQH6TP7.js";
+import "./chunk-OU2NQVKD.js";
 import {
   AuthHandler,
   DEFAULT_EXPERTS,
@@ -142,18 +142,18 @@ import {
   validateCommand,
   validateWorkflow,
   wrapInMarkdownFence
-} from "./chunk-RJEP2AZW.js";
-import "./chunk-GET2MTLW.js";
+} from "./chunk-76R5ES6Z.js";
+import "./chunk-Z6DXZ6AS.js";
 import "./chunk-3ACDP4E6.js";
 import {
   CATEGORY_DISPLAY_NAMES,
   DEFAULT_PR_REVIEW_CONFIG
 } from "./chunk-WAYGXUSM.js";
-import "./chunk-PM63X3QG.js";
-import "./chunk-CI5KGCX5.js";
+import "./chunk-E64SZTEP.js";
+import "./chunk-FVSZLVMR.js";
 import {
   shutdownExpertBridge
-} from "./chunk-RAWF4JOT.js";
+} from "./chunk-VI7LELES.js";
 import {
   ConsensusVoteInputSchema,
   DEFAULT_VOTE_TIMEOUT_MS,
@@ -162,25 +162,25 @@ import {
   VoteThresholdSchema,
   executeVoting,
   registerConsensusVoteTool
-} from "./chunk-4CVITS5D.js";
+} from "./chunk-DLUFDKPA.js";
 import {
   loadUsageEvents,
   rollupByModel
-} from "./chunk-TGGR6ST5.js";
+} from "./chunk-COJOUIO2.js";
 import {
   synthesizeResearch
-} from "./chunk-EFDXX5MC.js";
+} from "./chunk-UDB5NHJI.js";
 import {
   classifyTrust,
   createFullGitHubProvider,
   evaluatePolicy,
   parsePRUrl
-} from "./chunk-J435FU54.js";
-import "./chunk-4DLHM6LI.js";
+} from "./chunk-FUJ3XR7T.js";
+import "./chunk-FSFF7EFR.js";
 import {
   ReputationCache,
   sanitizeInput
-} from "./chunk-QMCHVYZB.js";
+} from "./chunk-EHLJLIHS.js";
 import {
   ImprovementReviewInputSchema,
   calculateFitnessScore,
@@ -194,10 +194,10 @@ import {
   registerImprovementReviewTool,
   runImprovementReview,
   scanForSecrets
-} from "./chunk-ZVBGZBW5.js";
+} from "./chunk-7TQZR5VU.js";
 import {
   createDefaultPolicyFirewall
-} from "./chunk-4CLBJ2NA.js";
+} from "./chunk-6UCWR3DS.js";
 import "./chunk-HFOQKCD2.js";
 import {
   PaperStatusSchema,
@@ -221,20 +221,20 @@ import {
   loadSourcesRegistry,
   rankDiscoveredItems,
   saveSourcesRegistry
-} from "./chunk-S4U3Z6ZS.js";
+} from "./chunk-QZUT22LP.js";
 import {
   resolveToken
-} from "./chunk-ZQEQVCIU.js";
+} from "./chunk-MY52DFXC.js";
 import {
   loadPapersRegistry,
   loadTechniquesRegistry,
   savePapersRegistry
-} from "./chunk-2CLFX73Y.js";
+} from "./chunk-B26FGLIJ.js";
 import {
   MemoryError,
   shutdownToolMemory
-} from "./chunk-GYDO2WOR.js";
-import "./chunk-NZGNOXXW.js";
+} from "./chunk-33MFMXBQ.js";
+import "./chunk-FPMQ2JAK.js";
 import {
   CustomExpertDefinitionSchema,
   DATA_SUBDIRECTORIES,
@@ -254,7 +254,7 @@ import {
   loadConfig,
   runDoctor,
   validateNexusEnv
-} from "./chunk-HGUO36KW.js";
+} from "./chunk-7GSYICTL.js";
 import "./chunk-NUBSJGQZ.js";
 import {
   capitalize,
@@ -265,20 +265,20 @@ import "./chunk-ZM4O442V.js";
 import "./chunk-PQHVC4BD.js";
 import {
   createUnifiedRegistry
-} from "./chunk-XIFOAZ5B.js";
+} from "./chunk-WYJJUF6N.js";
 import {
   createAllAdapters,
   getAvailableClis,
   isRecord,
   probeAllClis
-} from "./chunk-VZCQRLXT.js";
+} from "./chunk-3EYXPV5F.js";
 import {
   DEFAULTS
-} from "./chunk-WHZD2W6Q.js";
-import "./chunk-ECDJM6UB.js";
-import "./chunk-ZTRBMKXK.js";
-import "./chunk-7BONPRR2.js";
-import "./chunk-E4IYX7LD.js";
+} from "./chunk-ZMDOGN33.js";
+import "./chunk-WFKVUZ3O.js";
+import "./chunk-F74ZGHAP.js";
+import "./chunk-PFBV5FCT.js";
+import "./chunk-ORQAFTAZ.js";
 import {
   API_TIMEOUTS,
   AgentCapability,
@@ -352,16 +352,16 @@ import {
   validateTimeout,
   writeEmptyLine,
   writeLine
-} from "./chunk-QJIHSQZX.js";
+} from "./chunk-DBDWMHUL.js";
 import {
   applyPortableMode,
   detectSandbox,
   findRepoRoot,
-  getNexusDataDir,
   getPerRepoSubdirs,
   nexusDataPath,
+  nexusSharedPath,
   sessionsDbPath
-} from "./chunk-RUSP5PJR.js";
+} from "./chunk-GZ4NF4ZW.js";
 import "./chunk-ZPWHCABL.js";
 
 // src/cli/cli-log-bootstrap.ts
@@ -1629,14 +1629,14 @@ ${colors.dim}Session ended.${colors.reset}
     });
   });
   rl.prompt();
-  return new Promise((resolve13) => {
+  return new Promise((resolve14) => {
     rl.on("line", (line) => {
       void (async () => {
         try {
           const shouldExit = await processLine(line, session, logger19);
           if (shouldExit) {
             rl.close();
-            resolve13();
+            resolve14();
             return;
           }
         } catch (error) {
@@ -1648,7 +1648,7 @@ ${colors.dim}Session ended.${colors.reset}
       })();
     });
     rl.on("close", () => {
-      resolve13();
+      resolve14();
     });
   });
 }
@@ -2984,7 +2984,10 @@ var COMMAND_CATALOG = [
   },
   {
     command: "vote",
-    description: "Run consensus vote on a proposal (5-6 agents)",
+    // Default panel is 7 roles; `--quick` runs 3 (getVoterRoles in
+    // mcp/tools/consensus-vote.ts). Prior drift: "5-6 agents" here, "6 agents"
+    // in HELP_TEXT, "6 agents by default" in COMMAND_HELP — all wrong (#3209).
+    description: "Run consensus vote on a proposal (7 agents; --quick uses 3)",
     audience: "essential"
   },
   {
@@ -3227,6 +3230,9 @@ function filterCatalog(showAll) {
 function catalogForExtractors() {
   return COMMAND_CATALOG.filter((e) => e.command !== "(default)");
 }
+function getCommandDescription(command) {
+  return COMMAND_CATALOG.find((e) => e.command === command)?.description;
+}
 function groupByAudience(entries) {
   const groups = /* @__PURE__ */ new Map();
   for (const entry of entries) {
@@ -3265,7 +3271,8 @@ function renderCommandsSection(showAll) {
 }
 
 // src/cli-help-text.ts
-var HELP_TEXT = `
+var COMMANDS_PLACEHOLDER = "__COMMANDS__";
+var HELP_TEXT_FRAME = `
 nexus-agents - Intelligent orchestration platform for AI coding tools
 
 USAGE:
@@ -3273,44 +3280,7 @@ USAGE:
   nexus-agents [COMMAND] [SUBCOMMAND] [OPTIONS]
 
 COMMANDS:
-  (default)       Start MCP server with stdio transport
-  hello           Show welcome message and quick start (no API keys needed)
-  demo            API-free exploration mode (no API keys needed)
-  setup           Configure Claude CLI integration (MCP + CLAUDE.md rules)
-  login           Show per-CLI auth status + login fix instructions
-  verify          Quick installation verification (no API keys needed)
-  doctor          Check CLI installations and health status
-  config          Manage configuration (init, get, set, list, reset, export, import)
-  expert list     List available experts (built-in and custom)
-  workflow list   List available workflow templates
-  workflow run    Execute a workflow template
-  review <url>    Review a GitHub pull request (dogfooding)
-  routing-audit   Debug model routing decisions
-  orchestrate     Execute task using CLI tools (standalone mode)
-  vote            Run consensus vote on a proposal (6 agents)
-  system-review   Run automated system review (5-phase checklist)
-  sprint          Automated sprint planning from open issues
-  session         Manage session persistence (list, show, export, delete, prune)
-  evaluate        Self-evaluation of codebase components
-  issue           Issue template validation and management
-  index           Generate and manage codebase index
-  research        Manage research registry and index
-  validation      Show learning validation dashboard
-  learning-metrics Show aggregated learning metrics dashboard
-  swe-bench       Run SWE-bench evaluation benchmark
-  atbench         Run ATBench trajectory-safety evaluation (#1981)
-  hooks           Claude CLI hook integration commands
-  fitness-audit   Run CLI orchestration fitness score audit
-  release-notes   Generate release notes from git commits
-  release-validate Run expert swarm validation for releases
-  release-announce Generate release announcements (blog, Bluesky)
-  scaffold        Generate project files from templates (tool, expert, workflow, command)
-  visualize       Generate Mermaid diagrams and ASCII dashboards (architecture, swarm, flow)
-  capabilities    Show model capabilities matrix (modalities, tools, features)
-  status          At-a-glance project health dashboard (fitness, adapters, version)
-  health          Swarm health metrics dashboard (utilization, routing accuracy, failures)
-  validate        Run unified validation (doctor + fitness + config)
-  auth            Manage MCP authentication tokens (init, show, rotate)
+${COMMANDS_PLACEHOLDER}
 
 OPTIONS:
   -h, --help           Show this help message
@@ -3336,14 +3306,13 @@ EXAMPLES:
 
 For more information, visit: https://github.com/nexus-substrate/nexus-agents
 `.trim();
-var COMMANDS_BLOCK_RE = /COMMANDS:\n([\s\S]*?)\n\nOPTIONS:/;
+function composeHelp(commandsSection) {
+  return HELP_TEXT_FRAME.replace(COMMANDS_PLACEHOLDER, commandsSection);
+}
+var HELP_TEXT = composeHelp(renderCommandsSection(true));
 function renderHelp(opts) {
   if (opts.all) return HELP_TEXT;
-  const replacement = renderCommandsSection(false);
-  return HELP_TEXT.replace(COMMANDS_BLOCK_RE, `COMMANDS:
-${replacement}
-
-OPTIONS:`);
+  return composeHelp(renderCommandsSection(false));
 }
 
 // src/cli-types.ts
@@ -4055,7 +4024,7 @@ ${file.patch}
         violations: policyResult.violations
       });
     }
-    const { formatReviewComment: formatReviewComment2 } = await import("./pr-reviewer-helpers-PLKDVWYF.js");
+    const { formatReviewComment: formatReviewComment2 } = await import("./pr-reviewer-helpers-F3SHCHNV.js");
     const body = formatReviewComment2(result);
     const postResult = await provider.createReview(pr.prNumber, body, result.decision);
     if (!postResult.ok) {
@@ -12987,7 +12956,7 @@ function writeResultAndExit(result) {
 
 // src/cli/hooks/hook-router.ts
 async function readStdin() {
-  return new Promise((resolve13, reject) => {
+  return new Promise((resolve14, reject) => {
     let data = "";
     process.stdin.setEncoding("utf8");
     process.stdin.on("readable", () => {
@@ -12998,24 +12967,24 @@ async function readStdin() {
       }
     });
     process.stdin.on("end", () => {
-      resolve13(data);
+      resolve14(data);
     });
     process.stdin.on("error", (err2) => {
       reject(err2);
     });
     if (process.stdin.isTTY) {
-      resolve13("");
+      resolve14("");
     }
   });
 }
 async function readStdinWithTimeout(timeoutMs = 5e3) {
-  return new Promise((resolve13, reject) => {
+  return new Promise((resolve14, reject) => {
     const timeout2 = setTimeout(() => {
       reject(new Error(`Stdin read timeout after ${String(timeoutMs)}ms`));
     }, timeoutMs);
     readStdin().then((data) => {
       clearTimeout(timeout2);
-      resolve13(data);
+      resolve14(data);
     }).catch((err2) => {
       clearTimeout(timeout2);
       reject(err2 instanceof Error ? err2 : new Error(String(err2)));
@@ -14505,9 +14474,9 @@ function interactiveIO() {
     write: (text) => {
       process.stdout.write(text);
     },
-    prompt: (question) => new Promise((resolve13) => {
+    prompt: (question) => new Promise((resolve14) => {
       rl.question(question, (answer) => {
-        resolve13(answer.trim());
+        resolve14(answer.trim());
       });
     }),
     close: () => {
@@ -16956,9 +16925,6 @@ function authCommand(subcommand, options) {
   return result.success;
 }
 
-// src/cli-commands-handlers.ts
-import { existsSync as existsSync22 } from "fs";
-
 // src/cli/init-portable.ts
 import {
   existsSync as existsSync21,
@@ -17042,8 +17008,8 @@ function autoGitignoreMcpConfig(workspaceDir, dryRun) {
     if (already) return false;
   }
   if (!dryRun) {
-    const sep3 = existing.length > 0 && !existing.endsWith("\n") ? "\n" : "";
-    appendFileSync(gitignorePath, `${sep3}${MCP_CONFIG_FILENAME}
+    const sep4 = existing.length > 0 && !existing.endsWith("\n") ? "\n" : "";
+    appendFileSync(gitignorePath, `${sep4}${MCP_CONFIG_FILENAME}
 `, "utf-8");
   }
   return true;
@@ -17282,8 +17248,8 @@ function maybeUpdateGitignore(workspaceDir, portableDirName, dryRun) {
     }
   }
   if (!dryRun) {
-    const sep3 = existing.length > 0 && !existing.endsWith("\n") ? "\n" : "";
-    appendFileSync2(gitignorePath, `${sep3}${entry}
+    const sep4 = existing.length > 0 && !existing.endsWith("\n") ? "\n" : "";
+    appendFileSync2(gitignorePath, `${sep4}${entry}
 `, "utf-8");
   }
   return true;
@@ -17831,7 +17797,7 @@ function startImprovementReviewScheduler(options) {
   let running = false;
   const runOnce = async () => {
     try {
-      const { runImprovementReview: runImprovementReview2, ImprovementReviewInputSchema: ImprovementReviewInputSchema2 } = await import("./improvement-review-ZL3364R2.js");
+      const { runImprovementReview: runImprovementReview2, ImprovementReviewInputSchema: ImprovementReviewInputSchema2 } = await import("./improvement-review-77BKIQGN.js");
       const input = ImprovementReviewInputSchema2.parse({ fileIssues });
       const result = await runImprovementReview2(input, { logger: logger19 });
       logger19.info("Scheduled improvement_review complete", {
@@ -18219,8 +18185,8 @@ async function initUpstreamServers(gatewayConfig, server, logger19) {
     servers: upstreamServers.length,
     tools: tools.length
   });
-  const { z: z11 } = await import("zod");
-  const passthroughSchema = z11.looseObject({});
+  const { z: z14 } = await import("zod");
+  const passthroughSchema = z14.looseObject({});
   for (const tool of tools) {
     const toolName = tool.name;
     const desc = tool.description ?? `Upstream tool: ${toolName}`;
@@ -18617,7 +18583,7 @@ async function executeReplTask(task, options, logger19, rl) {
   }
 }
 function runOrchestratorRepl(options, logger19) {
-  return new Promise((resolve13) => {
+  return new Promise((resolve14) => {
     const rl = readline2.createInterface({
       input: process.stdin,
       output: process.stdout,
@@ -18640,7 +18606,7 @@ function runOrchestratorRepl(options, logger19) {
     });
     rl.on("close", () => {
       logger19.info("Orchestrator REPL closed");
-      resolve13();
+      resolve14();
     });
   });
 }
@@ -19774,7 +19740,7 @@ function adaptConfigToLibrary(config) {
 }
 function createBeliefPromoter() {
   return async (event) => {
-    const { getToolMemory } = await import("./tool-memory-Z2B7CAH7.js");
+    const { getToolMemory } = await import("./tool-memory-TSYJXGOV.js");
     const tm = getToolMemory();
     await tm.recordBelief(
       `skill:${event.name}`,
@@ -20517,18 +20483,7 @@ function buildOrchestratorOptions(args) {
     ...args.options.maxCostUsd !== void 0 && { maxCostUsd: args.options.maxCostUsd }
   };
 }
-function printFirstRunHint() {
-  const isTTY = process.stderr.isTTY;
-  if (!isTTY) return;
-  const dataDir = getNexusDataDir();
-  const hasConfig = existsSync22("./.nexus-agents/nexus-agents.yaml") || existsSync22("./.nexus-agents/nexus-agents.yml") || existsSync22("./nexus-agents.yaml") || existsSync22("./nexus-agents.yml");
-  if (existsSync22(dataDir) || hasConfig) return;
-  process.stderr.write(
-    "\n\x1B[36mnexus-agents\x1B[0m: First time? Run \x1B[1mnexus-agents setup\x1B[0m to configure.\n\n"
-  );
-}
 async function handleServerCommand(args) {
-  printFirstRunHint();
   if (args.options.interactive) {
     const exitCode = await replCommand({ verbose: args.options.verbose });
     return cliExitFromStatus(exitCode);
@@ -20638,7 +20593,7 @@ async function handleResearchCommand(args) {
   }
 }
 async function handleRegistryCommand(args) {
-  const { registryCommand, isValidRegistrySubcommand, formatRegistryUsage } = await import("./registry-command-HPKNLYUL.js");
+  const { registryCommand, isValidRegistrySubcommand, formatRegistryUsage } = await import("./registry-command-VFCSMHME.js");
   const subcommand = args.subcommand;
   if (!isValidRegistrySubcommand(subcommand)) {
     process.stdout.write(`${formatRegistryUsage()}
@@ -20686,7 +20641,7 @@ async function handleVerifyCommand(args) {
 async function handleDoctorCommand(args) {
   const exitCode = await doctorCommand({ fix: args.options.fix });
   if (args.options.deep) {
-    const { runDeepDiagnostics: runDeepDiagnostics2, formatDeepDiagnostics: formatDeepDiagnostics2 } = await import("./doctor-deep-HJ3NQ365.js");
+    const { runDeepDiagnostics: runDeepDiagnostics2, formatDeepDiagnostics: formatDeepDiagnostics2 } = await import("./doctor-deep-CZXN4YD6.js");
     const diag = runDeepDiagnostics2();
     process.stdout.write(formatDeepDiagnostics2(diag) + "\n");
   }
@@ -20736,7 +20691,7 @@ async function runInitPortableFlow(args) {
   return cliExit(result.success ? EXIT_CODES.SUCCESS : EXIT_CODES.SERVER_START_FAILED);
 }
 async function runInitOpencodeFlow(args) {
-  const { runInitOpencode } = await import("./init-opencode-L3NT524E.js");
+  const { runInitOpencode } = await import("./init-opencode-4H2VPN23.js");
   const opencodePath = args.options.opencode;
   if (opencodePath === void 0 || opencodePath === "") {
     process.stderr.write("Error: --opencode requires a path argument.\n");
@@ -20762,7 +20717,7 @@ async function runInitOpencodeFlow(args) {
   return cliExit(EXIT_CODES.SUCCESS);
 }
 async function renderOpencodeValidate(opencodePath) {
-  const { runOpencodeValidate } = await import("./init-opencode-L3NT524E.js");
+  const { runOpencodeValidate } = await import("./init-opencode-4H2VPN23.js");
   const result = await runOpencodeValidate(opencodePath);
   if (!result.ok) {
     process.stderr.write(`init --opencode --validate: ${result.reason ?? "failed"}
@@ -20801,7 +20756,7 @@ async function handleSetupCommandAsync(args) {
   return cliExitFromStatus(exitCode);
 }
 async function runCustomApiSetup(args) {
-  const { configureCustomApi } = await import("./setup-custom-api-W7EDVKWR.js");
+  const { configureCustomApi } = await import("./setup-custom-api-NJGCRIRO.js");
   const baseUrl = args.options.customApi;
   if (baseUrl === void 0) return EXIT_CODES.SERVER_START_FAILED;
   const input = {
@@ -22534,7 +22489,7 @@ function checkCircularDependencies(workflow) {
 var defaultStubFactory = {
   createAgentStub(agentType, action) {
     return async (inputs) => {
-      await new Promise((resolve13) => setTimeout(resolve13, 10));
+      await new Promise((resolve14) => setTimeout(resolve14, 10));
       return {
         stepId: `${agentType}-${action}`,
         status: "success",
@@ -23162,7 +23117,10 @@ var ACTION_BY_CATEGORY = {
   consensus: "investigate",
   // #3852: a deprecation/consolidation candidate is a human decision, never an
   // autonomous code change — investigate only (Epic D ratification path).
-  "tool-fitness": "investigate"
+  "tool-fitness": "investigate",
+  // #3692/#3246: a perf regression needs root-cause diagnosis before any change —
+  // investigate only; the surfaced signal never auto-applies a fix.
+  "perf-regression": "investigate"
 };
 function clip(s, max) {
   return s.length > max ? s.slice(0, max) : s;
@@ -23343,8 +23301,16 @@ var RemediationStepSchema = z9.object({
 var RemediationPlanSchema = z9.object({
   /** Source signal key (mirrors ImprovementSignal.signalKey). */
   signalKey: z9.string().min(1).max(200),
-  /** Signal category (mirrors SignalCategory; 'tool-fitness' added #3852). */
-  category: z9.enum(["routing", "tech-debt", "bug", "security", "consensus", "tool-fitness"]),
+  /** Signal category (mirrors SignalCategory; 'tool-fitness' #3852, 'perf-regression' #3692). */
+  category: z9.enum([
+    "routing",
+    "tech-debt",
+    "bug",
+    "security",
+    "consensus",
+    "tool-fitness",
+    "perf-regression"
+  ]),
   summary: z9.string().min(1).max(1e3),
   steps: z9.array(RemediationStepSchema).min(1).max(20)
 }).strict();
@@ -23428,13 +23394,13 @@ function makeProposalPrImplementAdapter(opts) {
   };
 }
 function makeGitWorktreeOps(repoRoot) {
-  const git = async (args, cwd) => {
+  const git2 = async (args, cwd) => {
     await execFileAsync4("git", [...args], { cwd });
   };
   return {
     async addWorktree(branch, baseBranch) {
       const path21 = join19(repoRoot, ".nexus-worktrees", branch.replace(/\//g, "_"));
-      await git(["worktree", "add", "-b", branch, path21, baseBranch], repoRoot);
+      await git2(["worktree", "add", "-b", branch, path21, baseBranch], repoRoot);
       return path21;
     },
     async writeFileIn(worktreePath, relPath, content) {
@@ -23443,14 +23409,14 @@ function makeGitWorktreeOps(repoRoot) {
       await writeFile6(abs, content, "utf8");
     },
     async commitAll(worktreePath, message) {
-      await git(["add", "-A"], worktreePath);
-      await git(["commit", "-m", message], worktreePath);
+      await git2(["add", "-A"], worktreePath);
+      await git2(["commit", "-m", message], worktreePath);
     },
     async pushBranch(worktreePath, branch) {
-      await git(["push", "-u", "origin", branch], worktreePath);
+      await git2(["push", "-u", "origin", branch], worktreePath);
     },
     async removeWorktree(worktreePath) {
-      await git(["worktree", "remove", worktreePath, "--force"], repoRoot);
+      await git2(["worktree", "remove", worktreePath, "--force"], repoRoot);
     }
   };
 }
@@ -23632,6 +23598,689 @@ function buildAutoRemediationDeps(opts = {}) {
   };
 }
 
+// src/mcp/tools/codepr-soak-consumer.ts
+import { createHash as createHash4 } from "crypto";
+
+// src/mcp/tools/codepr-orchestrator.ts
+import { createHash as createHash3 } from "crypto";
+import { mkdtempSync, mkdirSync as mkdirSync6, writeFileSync as writeFileSync8, rmSync as rmSync2, realpathSync as realpathSync2 } from "fs";
+import { tmpdir } from "os";
+import { dirname as dirname13, join as join20 } from "path";
+import { execFileSync as execFileSync3 } from "child_process";
+import { z as z12 } from "zod";
+
+// src/mcp/tools/codepr-guards.ts
+import { realpathSync } from "fs";
+import { isAbsolute as isAbsolute4, resolve as resolve13, relative as relative5, sep as sep3, dirname as dirname12, basename as basename5 } from "path";
+import { z as z11 } from "zod";
+function deny(reason, detail) {
+  return { ok: false, reason, detail };
+}
+function errnoCode(err2) {
+  if (err2 !== null && typeof err2 === "object" && "code" in err2) {
+    const code = err2.code;
+    return typeof code === "string" ? code : void 0;
+  }
+  return void 0;
+}
+function confinePath(worktreeRoot, candidatePath, realpath = realpathSync) {
+  if (!isAbsolute4(worktreeRoot)) {
+    return deny("path_escape", "worktreeRoot must be an absolute path");
+  }
+  let resolvedRoot;
+  try {
+    resolvedRoot = realpath(worktreeRoot);
+  } catch {
+    return deny("path_escape", "worktreeRoot could not be resolved (fail-closed)");
+  }
+  const joined = isAbsolute4(candidatePath) ? candidatePath : resolve13(resolvedRoot, candidatePath);
+  const reassembled = resolveNewFilePath(joined, realpath);
+  if (reassembled === void 0) {
+    return deny("path_escape", "candidate path could not be resolved (fail-closed)");
+  }
+  if (!isWithin(resolvedRoot, reassembled)) {
+    return deny("path_escape", "resolved path is outside the worktree root");
+  }
+  return { ok: true, resolvedPath: reassembled };
+}
+function resolveNewFilePath(joined, realpath) {
+  let existing = joined;
+  const trailing = [];
+  for (; ; ) {
+    try {
+      existing = realpath(existing);
+      break;
+    } catch (err2) {
+      if (errnoCode(err2) !== "ENOENT") return void 0;
+      const parent = dirname12(existing);
+      if (parent === existing) return void 0;
+      trailing.push(basename5(existing));
+      existing = parent;
+    }
+  }
+  return trailing.length === 0 ? existing : resolve13(existing, ...trailing.reverse());
+}
+function isWithin(parent, child) {
+  if (child === parent) return true;
+  const rel = relative5(parent, child);
+  if (rel === "") return true;
+  if (rel === ".." || rel.startsWith(".." + sep3)) return false;
+  if (isAbsolute4(rel)) return false;
+  return true;
+}
+function basenamePosix(relPathPosix) {
+  const idx = relPathPosix.lastIndexOf("/");
+  return idx === -1 ? relPathPosix : relPathPosix.slice(idx + 1);
+}
+var SELF_GUARD_MODULE_BASENAMES = [
+  "codepr-guards",
+  // this guard module (+ its tests / future dir) — prefix match
+  "diff-secret-scan",
+  // reused: pre-push secret scan
+  "repo-root-detection",
+  // reused: repo-root / path confinement source
+  "audit-logger",
+  // reused: hash-chained audit log
+  "audit-types",
+  // reused: audit schemas/interfaces the guard imports
+  "improvement-enforce-readiness",
+  // the enable-readiness module (shadow→enforce gate)
+  "remediation-readiness-collector"
+  // companion readiness collector
+];
+function isSelfGuardPath(relPathPosix) {
+  const base = basenamePosix(relPathPosix);
+  for (const name of SELF_GUARD_MODULE_BASENAMES) {
+    if (base === name) return true;
+    if (base.startsWith(name + ".")) return true;
+    if (relPathPosix === name || relPathPosix.startsWith(name + "/")) return true;
+    if (relPathPosix.includes("/" + name + "/")) return true;
+  }
+  return false;
+}
+var SENSITIVE_PATH_RULES = [
+  {
+    category: "self_guard",
+    description: "the adapter\u2019s own guard code + reused safety primitives (precondition B)",
+    match: isSelfGuardPath
+  },
+  {
+    category: "governance",
+    description: "governance/** \u2014 voting, ratification, tier ledgers",
+    match: (p) => p === "governance" || p.startsWith("governance/") || p.includes("/governance/")
+  },
+  {
+    category: "workflow",
+    description: ".github/workflows/** \u2014 CI/CD definitions",
+    match: (p) => p.startsWith(".github/workflows/") || p.includes("/.github/workflows/")
+  },
+  {
+    category: "codeowners",
+    // `p` is already lower-cased by classifyPath (case-insensitive matching).
+    description: "any CODEOWNERS file",
+    match: (p) => basenamePosix(p) === "codeowners"
+  },
+  {
+    category: "audit",
+    description: "audit subsystem: src/audit/** (tamper-evidence \u2014 human-authored only)",
+    match: (p) => p === "src/audit" || p.startsWith("src/audit/") || p.includes("/src/audit/")
+  },
+  {
+    category: "authority",
+    description: "auth/authority code: **/authority-*, **/auth/**",
+    match: (p) => basenamePosix(p).startsWith("authority-") || p.includes("/auth/") || p.startsWith("auth/")
+  },
+  {
+    category: "dependency_manifest",
+    description: "dependency manifests: package.json, pnpm-lock.yaml, tsconfig*.json (precondition E)",
+    match: (p) => {
+      const base = basenamePosix(p);
+      if (base === "package.json") return true;
+      if (base === "pnpm-lock.yaml") return true;
+      if (base.startsWith("tsconfig") && base.endsWith(".json")) return true;
+      return false;
+    }
+  }
+];
+function normalizeRelPath(relPath) {
+  const adsIdx = relPath.indexOf("::");
+  let p = adsIdx === -1 ? relPath : relPath.slice(0, adsIdx);
+  p = p.replace(/\\/g, "/");
+  p = p.replace(/\/{2,}/g, "/");
+  while (p.startsWith("./")) p = p.slice(2);
+  p = p.split("/").map((seg) => seg.replace(/[. ]+$/, "")).join("/");
+  return p;
+}
+function classifyPath(relPath) {
+  const p = normalizeRelPath(relPath).toLowerCase();
+  for (const rule of SENSITIVE_PATH_RULES) {
+    if (rule.match(p)) return { sensitive: true, category: rule.category };
+  }
+  return { sensitive: false };
+}
+var BlastRadiusLimitsSchema = z11.object({
+  /** Max number of files the change may touch. Default 20. */
+  maxFiles: z11.number().int().positive().default(20),
+  /** Max total changed lines (added + removed across all files). Default 400. */
+  maxLines: z11.number().int().positive().default(400)
+}).strict();
+var DEFAULT_BLAST_RADIUS_LIMITS = Object.freeze(
+  BlastRadiusLimitsSchema.parse({})
+);
+function checkBlastRadius(changedFiles, limits = DEFAULT_BLAST_RADIUS_LIMITS) {
+  const parsed = BlastRadiusLimitsSchema.safeParse(limits);
+  if (!parsed.success) {
+    return deny("blast_radius_exceeded", "invalid blast-radius limits (fail-closed)");
+  }
+  const { maxFiles, maxLines } = parsed.data;
+  for (const f of changedFiles) {
+    const cls = classifyPath(f.path);
+    if (cls.sensitive) {
+      return deny("sensitive_path", `changed file is sensitive (${cls.category}): ${f.path}`);
+    }
+  }
+  const filesTouched = changedFiles.length;
+  if (filesTouched > maxFiles) {
+    return deny(
+      "blast_radius_exceeded",
+      `files touched ${String(filesTouched)} exceeds maxFiles ${String(maxFiles)}`
+    );
+  }
+  let linesTouched = 0;
+  for (const f of changedFiles) linesTouched += f.addedLines + f.removedLines;
+  if (linesTouched > maxLines) {
+    return deny(
+      "blast_radius_exceeded",
+      `changed lines ${String(linesTouched)} exceeds maxLines ${String(maxLines)}`
+    );
+  }
+  return { ok: true, filesTouched, linesTouched };
+}
+function scanDiffOrDeny(diff) {
+  const scan = scanForSecrets(diff);
+  if (!scan.clean) {
+    const summary = scan.findings.map((f) => `${f.pattern}@L${String(f.line)}`).join(", ");
+    return deny(
+      "secret_detected",
+      `secret scan found ${String(scan.findings.length)} finding(s): ${summary}`
+    );
+  }
+  return { ok: true, scan };
+}
+var AUTONOMOUS_ACTOR = {
+  type: "system",
+  id: "autonomous-code-pr",
+  name: "Autonomous Code-PR Adapter (Stage 1, OFF)"
+};
+function auditAutonomousEvent(logger19, record) {
+  try {
+    logger19.log({
+      category: "security",
+      severity: record.decision === "abort" ? "warning" : "info",
+      outcome: record.decision === "abort" ? "denied" : "success",
+      action: `autonomous_code_pr.${record.decision}`,
+      description: record.decision === "abort" ? `autonomous code-PR aborted (${record.abortReason ?? "unspecified"})` : "autonomous code-PR write-guards passed (would open PR)",
+      actor: record.actor ?? AUTONOMOUS_ACTOR,
+      resource: { type: "autonomous-run", id: record.runId, name: record.runId },
+      metadata: {
+        runId: record.runId,
+        sourceSignalHash: record.sourceSignalHash,
+        diffHash: record.diffHash,
+        scanVerdict: record.scanVerdict,
+        filesTouched: record.filesTouched,
+        linesTouched: record.linesTouched,
+        tokenIdentity: record.tokenIdentity,
+        decision: record.decision,
+        abortReason: record.abortReason ?? null
+      }
+    });
+  } catch (err2) {
+    const detail = err2 instanceof Error ? err2.message : String(err2);
+    return deny("audit_append_failed", `audit append threw (fail-closed): ${detail}`);
+  }
+  return { ok: true };
+}
+var ResourceBudgetLimitsSchema = z11.object({
+  /** Wall-clock ceiling in ms. Default 600000 (10 min). */
+  maxWallClockMs: z11.number().int().positive().default(6e5),
+  /** Token ceiling. Default 200000. */
+  maxTokens: z11.number().int().positive().default(2e5),
+  /** Tool-call ceiling. Default 200. */
+  maxToolCalls: z11.number().int().positive().default(200)
+}).strict();
+var DEFAULT_RESOURCE_BUDGET_LIMITS = Object.freeze(
+  ResourceBudgetLimitsSchema.parse({})
+);
+function checkResourceBudget(usage, limits = DEFAULT_RESOURCE_BUDGET_LIMITS) {
+  const parsed = ResourceBudgetLimitsSchema.safeParse(limits);
+  if (!parsed.success) {
+    return deny("budget_exceeded", "invalid resource limits (fail-closed)");
+  }
+  const { maxWallClockMs, maxTokens, maxToolCalls } = parsed.data;
+  if (usage.wallClockMs > maxWallClockMs) {
+    return deny(
+      "budget_exceeded",
+      `wall-clock ${String(usage.wallClockMs)}ms exceeds ${String(maxWallClockMs)}ms`
+    );
+  }
+  if (usage.tokens > maxTokens) {
+    return deny("budget_exceeded", `tokens ${String(usage.tokens)} exceeds ${String(maxTokens)}`);
+  }
+  if (usage.toolCalls > maxToolCalls) {
+    return deny(
+      "budget_exceeded",
+      `tool calls ${String(usage.toolCalls)} exceeds ${String(maxToolCalls)}`
+    );
+  }
+  return { ok: true };
+}
+function evaluateWriteGuards(input) {
+  for (const f of input.changedFiles) {
+    const confined = runGuard(
+      "confinePath",
+      () => confinePath(input.worktreeRoot, f.path, input.realpath)
+    );
+    if (!confined.ok) return confined;
+  }
+  const blast = runGuard(
+    "checkBlastRadius",
+    () => checkBlastRadius(input.changedFiles, input.blastRadiusLimits)
+  );
+  if (!blast.ok) return blast;
+  const secrets = runGuard("scanDiffOrDeny", () => scanDiffOrDeny(input.diff));
+  if (!secrets.ok) return secrets;
+  const budget = runGuard(
+    "checkResourceBudget",
+    () => checkResourceBudget(input.usage, input.resourceLimits)
+  );
+  if (!budget.ok) return budget;
+  return { ok: true };
+}
+function runGuard(name, fn) {
+  try {
+    return fn();
+  } catch (err2) {
+    const message = err2 instanceof Error ? err2.message : String(err2);
+    return deny("guard_error", `guard ${name} threw (fail-closed): ${message}`);
+  }
+}
+
+// src/mcp/tools/codepr-orchestrator.ts
+var ProposedChangeSchema = z12.object({
+  /** Repo-relative path the change would write. */
+  relPath: z12.string().min(1),
+  /** The full new file content. */
+  newContent: z12.string()
+}).strict();
+var CodePrRunInputSchema = z12.object({
+  /** Correlates all audit events for this run. */
+  runId: z12.string().min(1),
+  /** Hash of the source signal (fitness/improvement) that triggered the run. */
+  sourceSignalHash: z12.string().min(1),
+  /** The proposed change set. */
+  changes: z12.array(ProposedChangeSchema).min(1)
+}).strict();
+var ORCHESTRATOR_USAGE_ZERO = { wallClockMs: 0, tokens: 0, toolCalls: 0 };
+function sha256(s) {
+  return createHash3("sha256").update(s).digest("hex");
+}
+function git(cwd, args) {
+  return execFileSync3("git", [...args], { cwd, encoding: "utf8", stdio: ["ignore", "pipe", "pipe"] });
+}
+function parseNumstat(numstat) {
+  const files = [];
+  for (const line of numstat.split("\n")) {
+    if (line.trim() === "") continue;
+    const parts = line.split("	");
+    if (parts.length < 3) continue;
+    const added = parts[0] === "-" ? 0 : Number.parseInt(parts[0] ?? "0", 10);
+    const removed = parts[1] === "-" ? 0 : Number.parseInt(parts[1] ?? "0", 10);
+    const path21 = parts.slice(2).join("	");
+    files.push({
+      path: path21,
+      addedLines: Number.isFinite(added) ? added : 0,
+      removedLines: Number.isFinite(removed) ? removed : 0
+    });
+  }
+  return files;
+}
+function denied(reason, detail, auditRecorded) {
+  return { ok: false, reason, detail, auditRecorded };
+}
+function auditAbort(logger19, a) {
+  const res = auditAutonomousEvent(logger19, {
+    runId: a.input.runId,
+    sourceSignalHash: a.input.sourceSignalHash,
+    diffHash: a.diffHash,
+    scanVerdict: a.reason === "secret_detected" ? "secret_detected" : "clean",
+    filesTouched: a.filesTouched,
+    linesTouched: a.linesTouched,
+    tokenIdentity: "none",
+    decision: "abort",
+    abortReason: a.reason
+  });
+  return res.ok;
+}
+function precheckChanges(worktreeRoot, run, logger19) {
+  for (const change of run.changes) {
+    const confined = confinePath(worktreeRoot, change.relPath);
+    if (!confined.ok) {
+      const recorded = auditAbort(logger19, {
+        input: run,
+        reason: confined.reason,
+        diffHash: sha256(""),
+        filesTouched: 0,
+        linesTouched: 0
+      });
+      return denied(confined.reason, confined.detail, recorded);
+    }
+    const cls = classifyPath(change.relPath);
+    if (cls.sensitive) {
+      const recorded = auditAbort(logger19, {
+        input: run,
+        reason: "sensitive_path",
+        diffHash: sha256(""),
+        filesTouched: 0,
+        linesTouched: 0
+      });
+      return denied("sensitive_path", `sensitive path (${cls.category}): ${change.relPath}`, recorded);
+    }
+  }
+  return void 0;
+}
+function applyChanges(worktreeRoot, run) {
+  for (const change of run.changes) {
+    const confined = confinePath(worktreeRoot, change.relPath);
+    if (!confined.ok) throw new Error(`apply: ${confined.detail}`);
+    mkdirSync6(dirname13(confined.resolvedPath), { recursive: true });
+    writeFileSync8(confined.resolvedPath, change.newContent);
+  }
+}
+function realizeDiff(worktreeRoot) {
+  git(worktreeRoot, ["add", "-A"]);
+  const diffText = git(worktreeRoot, ["diff", "--cached"]);
+  const changedFiles = parseNumstat(git(worktreeRoot, ["diff", "--cached", "--numstat"]));
+  let linesTouched = 0;
+  for (const f of changedFiles) linesTouched += f.addedLines + f.removedLines;
+  return { diffText, diffHash: sha256(diffText), changedFiles, linesTouched };
+}
+function runGuardsAndPlan(args, logger19) {
+  const { worktreeRoot, run, realized } = args;
+  const verdict = evaluateWriteGuards({
+    worktreeRoot,
+    changedFiles: realized.changedFiles,
+    diff: realized.diffText,
+    usage: args.usage,
+    blastRadiusLimits: args.blastRadiusLimits,
+    resourceLimits: args.resourceLimits
+  });
+  if (!verdict.ok) {
+    const recorded = auditAbort(logger19, {
+      input: run,
+      reason: verdict.reason,
+      diffHash: realized.diffHash,
+      filesTouched: realized.changedFiles.length,
+      linesTouched: realized.linesTouched
+    });
+    return denied(verdict.reason, verdict.detail, recorded);
+  }
+  const plan = {
+    branchName: `auto/codepr/${run.runId}`,
+    title: `auto code-PR (dry-run, NO push) for run ${run.runId}`,
+    files: realized.changedFiles.map((f) => ({
+      path: f.path,
+      addedLines: f.addedLines,
+      removedLines: f.removedLines
+    })),
+    filesTouched: realized.changedFiles.length,
+    linesTouched: realized.linesTouched,
+    diffHash: realized.diffHash
+  };
+  const audit = auditAutonomousEvent(logger19, {
+    runId: run.runId,
+    sourceSignalHash: run.sourceSignalHash,
+    diffHash: realized.diffHash,
+    scanVerdict: "clean",
+    filesTouched: plan.filesTouched,
+    linesTouched: plan.linesTouched,
+    tokenIdentity: "none",
+    decision: "would_open_pr"
+  });
+  if (!audit.ok) {
+    return denied(audit.reason, audit.detail, false);
+  }
+  return { ok: true, plan, auditRecorded: true };
+}
+function runInWorktree(run, logger19, options, handle) {
+  const fault = options.faultInjector;
+  const repoRoot = options.repoRoot ?? process.cwd();
+  handle.tempParent = realpathSync2(mkdtempSync(join20(tmpdir(), "codepr-orchestrator-")));
+  handle.worktreeRoot = join20(handle.tempParent, "wt");
+  git(repoRoot, ["worktree", "add", "--detach", handle.worktreeRoot]);
+  fault?.("after-worktree");
+  const precheck = precheckChanges(handle.worktreeRoot, run, logger19);
+  if (precheck !== void 0) return precheck;
+  applyChanges(handle.worktreeRoot, run);
+  fault?.("after-apply");
+  const realized = realizeDiff(handle.worktreeRoot);
+  fault?.("after-diff");
+  return runGuardsAndPlan(
+    {
+      worktreeRoot: handle.worktreeRoot,
+      run,
+      realized,
+      usage: options.usage ?? ORCHESTRATOR_USAGE_ZERO,
+      blastRadiusLimits: options.blastRadiusLimits,
+      resourceLimits: options.resourceLimits
+    },
+    logger19
+  );
+}
+function discardWorktree(repoRoot, handle) {
+  if (handle.worktreeRoot !== void 0) {
+    try {
+      git(repoRoot, ["worktree", "remove", "--force", handle.worktreeRoot]);
+    } catch {
+    }
+  }
+  if (handle.tempParent !== void 0) {
+    try {
+      rmSync2(handle.tempParent, { recursive: true, force: true });
+    } catch {
+    }
+  }
+}
+function planCodePrRun(input, logger19, options = {}) {
+  const parsed = CodePrRunInputSchema.safeParse(input);
+  if (!parsed.success) {
+    return denied("guard_error", "invalid code-PR run input (fail-closed)", false);
+  }
+  const run = parsed.data;
+  const repoRoot = options.repoRoot ?? process.cwd();
+  const handle = {};
+  try {
+    return runInWorktree(run, logger19, options, handle);
+  } catch (err2) {
+    const message = err2 instanceof Error ? err2.message : String(err2);
+    let recorded = false;
+    try {
+      recorded = auditAbort(logger19, {
+        input: run,
+        reason: "guard_error",
+        diffHash: sha256(""),
+        filesTouched: 0,
+        linesTouched: 0
+      });
+    } catch {
+      recorded = false;
+    }
+    return denied("guard_error", `orchestrator failed (fail-closed): ${message}`, recorded);
+  } finally {
+    discardWorktree(repoRoot, handle);
+  }
+}
+
+// src/mcp/tools/codepr-soak-store.ts
+import { z as z13 } from "zod";
+var CodePrSoakRecordSchema = z13.object({
+  /** ISO-8601 capture time. */
+  timestamp: z13.string(),
+  /** Correlates the data point to the dry-run's orchestrator runId. */
+  runId: z13.string(),
+  /** The improvement signal's stable key that triggered the dry-run. */
+  signalKey: z13.string(),
+  /** True when the dry-run plan succeeded with ZERO guard denial. */
+  green: z13.boolean(),
+  /** The guard denial reason when `green` is false; omitted for a green plan. */
+  denialReason: z13.string().optional(),
+  /** Files the dry-run plan touched (0 on denial before the diff was realized). */
+  filesTouched: z13.number().int().nonnegative()
+}).strict();
+var CODEPR_SOAK_MAX_RECORDS = 1e4;
+function getCodePrSoakFile() {
+  return nexusDataPath("learning", "codepr-guards-soak.jsonl");
+}
+function createCodePrSoakSink(filePath = getCodePrSoakFile(), maxRecords = CODEPR_SOAK_MAX_RECORDS) {
+  const store = new JsonlStore({
+    filePath,
+    schema: CodePrSoakRecordSchema,
+    maxRecords,
+    component: "CodePrSoakSink"
+  });
+  return {
+    record(record) {
+      store.append(record);
+    },
+    getRecords() {
+      return store.all();
+    }
+  };
+}
+var soakSingleton;
+function getCodePrSoakSink() {
+  soakSingleton ??= createCodePrSoakSink();
+  return soakSingleton;
+}
+function greenCodePrSoakRecord(args) {
+  return {
+    timestamp: new Date(getTimeProvider().now()).toISOString(),
+    runId: args.runId,
+    signalKey: args.signalKey,
+    green: true,
+    filesTouched: args.filesTouched
+  };
+}
+function deniedCodePrSoakRecord(args) {
+  return {
+    timestamp: new Date(getTimeProvider().now()).toISOString(),
+    runId: args.runId,
+    signalKey: args.signalKey,
+    green: false,
+    denialReason: args.denialReason,
+    filesTouched: 0
+  };
+}
+
+// src/mcp/tools/codepr-soak-consumer.ts
+var CODE_TOUCHING_KINDS = /* @__PURE__ */ new Set([
+  "add-test",
+  "refactor",
+  "update-docs",
+  "fix-bug"
+]);
+function planTouchesCode(plan) {
+  return plan.steps.some((s) => CODE_TOUCHING_KINDS.has(s.kind));
+}
+function placeholderPathFor(plan, kind) {
+  const h = createHash4("sha256").update(`${plan.signalKey}:${kind}`).digest("hex").slice(0, 12);
+  return `src/__codepr_soak__/${kind}-${h}.ts`;
+}
+function deriveProposedChanges(plan) {
+  const seen = /* @__PURE__ */ new Set();
+  const changes = [];
+  for (const step of plan.steps) {
+    if (!CODE_TOUCHING_KINDS.has(step.kind)) continue;
+    const path21 = step.targetPath !== void 0 && step.targetPath !== "" ? step.targetPath : placeholderPathFor(plan, step.kind);
+    if (seen.has(path21)) continue;
+    seen.add(path21);
+    changes.push({
+      relPath: path21,
+      newContent: `// codepr soak dry-run placeholder for ${plan.signalKey} (${step.kind})
+`
+    });
+  }
+  return changes;
+}
+function loggerBackedAuditLogger(logger19) {
+  return {
+    log: (input) => {
+      logger19.debug("codepr soak dry-run audit event", {
+        action: input.action,
+        outcome: input.outcome
+      });
+    },
+    logToolInvocation: () => {
+    },
+    logPolicyDecision: () => {
+    },
+    logSecurityEvent: () => {
+    },
+    logRateLimitViolation: () => {
+    },
+    logTierTransition: () => {
+    },
+    flush: () => Promise.resolve(),
+    close: () => Promise.resolve()
+  };
+}
+function soakRunId(plan) {
+  return `codepr-soak-${createHash4("sha256").update(plan.signalKey).digest("hex").slice(0, 16)}`;
+}
+function sourceSignalHash(plan) {
+  return createHash4("sha256").update(plan.signalKey).digest("hex");
+}
+function runCodePrSoak(plan, inject = {}) {
+  const logger19 = inject.logger ?? createLogger({ tool: "codepr-soak" });
+  try {
+    soakOnce(plan, inject, logger19);
+  } catch (err2) {
+    logger19.warn("codepr soak step failed (swallowed; cycle proceeds)", {
+      signalKey: plan.signalKey,
+      error: getErrorMessage(err2)
+    });
+  }
+}
+function soakOnce(plan, inject, logger19) {
+  if (!planTouchesCode(plan)) return;
+  const changes = deriveProposedChanges(plan);
+  if (changes.length === 0) return;
+  const runId = soakRunId(plan);
+  const planRun = inject.planRun ?? planCodePrRun;
+  const result = planRun(
+    { runId, sourceSignalHash: sourceSignalHash(plan), changes },
+    inject.auditLogger ?? loggerBackedAuditLogger(logger19),
+    inject.orchestratorOptions ?? {}
+  );
+  const sink = inject.sink ?? getCodePrSoakSink();
+  if (result.ok) {
+    sink.record(
+      greenCodePrSoakRecord({ runId, signalKey: plan.signalKey, filesTouched: result.plan.filesTouched })
+    );
+    logger19.debug("codepr soak: green dry-run recorded", {
+      signalKey: plan.signalKey,
+      filesTouched: result.plan.filesTouched
+    });
+  } else {
+    sink.record(
+      deniedCodePrSoakRecord({ runId, signalKey: plan.signalKey, denialReason: result.reason })
+    );
+    logger19.debug("codepr soak: denied dry-run recorded (streak reset)", {
+      signalKey: plan.signalKey,
+      reason: result.reason
+    });
+  }
+}
+
 // src/mcp/tools/improvement-remediation-guard.ts
 var DEFAULT_REMEDIATION_GUARD_CONFIG = {
   cooldownMs: 6 * 60 * 60 * 1e3,
@@ -23974,6 +24623,17 @@ ${renderPlanAsResearch(plan)}`;
   }
   return null;
 }
+function firePlanObserver(deps, signal, plan) {
+  if (deps.onPlanProduced === void 0) return;
+  try {
+    deps.onPlanProduced(signal, plan);
+  } catch (err2) {
+    deps.logger?.warn("onPlanProduced observer threw (swallowed)", {
+      signalKey: signal.signalKey,
+      error: err2 instanceof Error ? err2.message : String(err2)
+    });
+  }
+}
 async function executeOne(signal, deps, mode, ctx) {
   const { guard, now, requirement } = ctx;
   const ledger = new CapabilityLedger();
@@ -23991,6 +24651,7 @@ async function executeOne(signal, deps, mode, ctx) {
     signalKey: signal.signalKey,
     detail: `${String(plan.steps.length)} steps`
   });
+  firePlanObserver(deps, signal, plan);
   const protectedPaths = planTouchesProtectedPath(plan);
   if (protectedPaths.protected) {
     const reason = `protected path(s) ${protectedPaths.paths.join(", ")} \u2014 human attestation required`;
@@ -24024,7 +24685,7 @@ async function runAutoRemediationCycle(config = {}, inject = {}) {
   logger19.info(`auto-remediation cycle: ${mode} over ${String(signals.length)} signals`);
   if (mode === "audit") {
     const collector = buildSoakCollector(signals, inject);
-    const soakDeps = withSoakAudit(deps, collector);
+    const soakDeps = withCodePrSoak(withSoakAudit(deps, collector), inject);
     try {
       return await runAutoRemediation(signals, soakDeps, { mode });
     } finally {
@@ -24033,6 +24694,15 @@ async function runAutoRemediationCycle(config = {}, inject = {}) {
   }
   return runAutoRemediation(signals, deps, { mode });
 }
+function withCodePrSoak(deps, inject) {
+  const runSoak = inject.runCodePrSoak ?? runCodePrSoak;
+  return {
+    ...deps,
+    onPlanProduced: (_signal, plan) => {
+      runSoak(plan, inject.codePrSoak);
+    }
+  };
+}
 function buildSoakCollector(signals, inject) {
   const meta = /* @__PURE__ */ new Map();
   for (const s of signals) {
@@ -24204,18 +24874,18 @@ async function handleRemediationReviewCommand(args) {
 }
 
 // src/cli/migrate-command.ts
-import { cpSync, existsSync as existsSync24, mkdirSync as mkdirSync6, readdirSync as readdirSync3 } from "fs";
+import { cpSync, existsSync as existsSync23, mkdirSync as mkdirSync7, readdirSync as readdirSync3 } from "fs";
 import { homedir } from "os";
-import { join as join20 } from "path";
+import { join as join21 } from "path";
 var logger18 = createLogger({ component: "migrate-command" });
-var HOMEDIR_DEFAULT_BASE = join20(homedir(), ".nexus-agents");
+var HOMEDIR_DEFAULT_BASE = join21(homedir(), ".nexus-agents");
 function countItems(dir) {
-  if (!existsSync24(dir)) return 0;
+  if (!existsSync23(dir)) return 0;
   try {
     const entries = readdirSync3(dir, { withFileTypes: true });
     let n = 0;
     for (const e of entries) {
-      const p = join20(dir, e.name);
+      const p = join21(dir, e.name);
       if (e.isDirectory()) {
         n += countItems(p);
       } else {
@@ -24257,7 +24927,7 @@ function checkEarlyExits(fromBase, toBase, dryRun) {
       summary: "No git repo detected from cwd. Run from inside a repo or pass --to <path> to choose an explicit destination."
     };
   }
-  if (!existsSync24(fromBase)) {
+  if (!existsSync23(fromBase)) {
     return {
       fromBase,
       toBase,
@@ -24270,8 +24940,8 @@ function checkEarlyExits(fromBase, toBase, dryRun) {
   return null;
 }
 function planAndExecuteEntry(name, fromBase, toBase, perRepoSet, dryRun) {
-  const source = join20(fromBase, name);
-  const target = join20(toBase, name);
+  const source = join21(fromBase, name);
+  const target = join21(toBase, name);
   if (!perRepoSet.has(name)) {
     return { subdir: name, status: "skipped-not-per-repo", source, target: "", itemsCopied: 0 };
   }
@@ -24279,11 +24949,11 @@ function planAndExecuteEntry(name, fromBase, toBase, perRepoSet, dryRun) {
   if (items === 0) {
     return { subdir: name, status: "skipped-empty", source, target, itemsCopied: 0 };
   }
-  if (existsSync24(target) && readdirSync3(target).length > 0) {
+  if (existsSync23(target) && readdirSync3(target).length > 0) {
     return { subdir: name, status: "skipped-exists", source, target, itemsCopied: 0 };
   }
   if (!dryRun) {
-    mkdirSync6(toBase, { recursive: true });
+    mkdirSync7(toBase, { recursive: true });
     cpSync(source, target, { recursive: true, errorOnExist: false });
   }
   return { subdir: name, status: "copied", source, target, itemsCopied: items };
@@ -24291,7 +24961,7 @@ function planAndExecuteEntry(name, fromBase, toBase, perRepoSet, dryRun) {
 function resolveDefaultTarget(cwd) {
   const repoRoot = findRepoRoot(cwd);
   if (repoRoot === null) return null;
-  return join20(repoRoot, ".nexus-agents");
+  return join21(repoRoot, ".nexus-agents");
 }
 function formatMigrationResult(result) {
   if (!result.success) {
@@ -24332,6 +25002,32 @@ async function handleMigrateCommand(args) {
   return cliExit(result.success ? EXIT_CODES.SUCCESS : EXIT_CODES.SERVER_START_FAILED);
 }
 
+// src/cli/first-run-hint.ts
+import { existsSync as existsSync24, mkdirSync as mkdirSync8, writeFileSync as writeFileSync9 } from "fs";
+import { dirname as dirname14 } from "path";
+var HINT_SUPPRESSED_COMMANDS = /* @__PURE__ */ new Set(["version", "help", "setup"]);
+function firstRunMarkerPath() {
+  return nexusSharedPath(".first-run-done");
+}
+function maybeShowFirstRunHint(command) {
+  if (HINT_SUPPRESSED_COMMANDS.has(command)) return;
+  if (!process.stderr.isTTY) return;
+  const marker = firstRunMarkerPath();
+  try {
+    if (existsSync24(marker)) return;
+  } catch {
+  }
+  process.stderr.write(
+    "\x1B[36mnexus-agents\x1B[0m: First time? Run \x1B[1mnexus-agents setup\x1B[0m to configure.\n  (This one-time hint is now dismissed.)\n"
+  );
+  try {
+    mkdirSync8(dirname14(marker), { recursive: true });
+    writeFileSync9(marker, `${(/* @__PURE__ */ new Date()).toISOString()}
+`, { flag: "w" });
+  } catch {
+  }
+}
+
 // src/cli-commands.ts
 function printHelp(args) {
   const all = args?.options.all ?? false;
@@ -24454,6 +25150,7 @@ async function handleAsyncCommand(args) {
 }
 async function dispatchCommand(args) {
   initDataDirectories();
+  maybeShowFirstRunHint(args.command);
   bootstrapStepNotifications({ mode: args.command === "server" ? "mcp-stdio" : "cli" });
   if (!handleSyncCommand(args)) {
     await handleAsyncCommand(args);
@@ -24463,7 +25160,6 @@ async function dispatchCommand(args) {
 // src/cli-command-help.ts
 var ORCHESTRATE_HELP = {
   command: "orchestrate",
-  description: "Execute a task using CLI tools (standalone mode). Routes to optimal model.",
   examples: [
     'nexus-agents orchestrate "Explain this function"',
     'nexus-agents orchestrate "Generate unit tests" --model=claude',
@@ -24486,7 +25182,6 @@ var ORCHESTRATE_HELP = {
 };
 var VOTE_HELP = {
   command: "vote",
-  description: "Run multi-agent consensus vote on a proposal (6 agents by default).",
   examples: [
     'nexus-agents vote --proposal "Add caching layer"',
     'nexus-agents vote -p "Migrate to PostgreSQL" -t supermajority',
@@ -24496,7 +25191,7 @@ var VOTE_HELP = {
   flags: [
     { flag: "-p, --proposal <text>", description: "Proposal text to vote on (required)" },
     { flag: "-t, --threshold <t>", description: "Threshold: majority, supermajority, unanimous" },
-    { flag: "--quick", description: "Use 3 agents instead of 6 for faster votes" },
+    { flag: "--quick", description: "Use 3 agents instead of the full 7 for faster votes" },
     { flag: "--dry-run", description: "Simulate votes without agent execution" },
     { flag: "--timeout=<seconds>", description: "Timeout per vote in seconds", defaultValue: "90" },
     {
@@ -24509,7 +25204,6 @@ var VOTE_HELP = {
 };
 var EXPERT_HELP = {
   command: "expert",
-  description: "Manage expert agents. Subcommands: list, create, execute.",
   examples: ["nexus-agents expert list", "nexus-agents expert list --format=json"],
   flags: [
     {
@@ -24521,7 +25215,6 @@ var EXPERT_HELP = {
 };
 var WORKFLOW_HELP = {
   command: "workflow",
-  description: "Manage and run workflow templates. Subcommands: list, run.",
   examples: [
     "nexus-agents workflow list",
     `nexus-agents workflow run code-review --input='{"url":"https://github.com/o/r/pull/1"}'`,
@@ -24534,7 +25227,6 @@ var WORKFLOW_HELP = {
 };
 var DOCTOR_HELP = {
   command: "doctor",
-  description: "Check CLI installations, adapters, and system health.",
   examples: ["nexus-agents doctor", "nexus-agents doctor --deep", "nexus-agents doctor --fix"],
   flags: [
     { flag: "--deep", description: "Run deep health checks (adapter connectivity)" },
@@ -24544,7 +25236,6 @@ var DOCTOR_HELP = {
 };
 var MODE_HELP = {
   command: "mode",
-  description: "Inspect the detected invocation mode (server vs orchestrator), the signals that fed the decision, and the one-line reasoning. Useful for debugging unexpected modes in CI/containers.",
   examples: [
     "nexus-agents mode",
     "nexus-agents mode --format=json",
@@ -24560,7 +25251,6 @@ var MODE_HELP = {
 };
 var SETUP_HELP = {
   command: "setup",
-  description: "Configure MCP integration for Claude, Gemini, Codex, and OpenCode CLIs.",
   examples: [
     "nexus-agents setup",
     "nexus-agents setup --interactive",
@@ -24597,7 +25287,6 @@ var SETUP_HELP = {
 };
 var CONFIG_HELP = {
   command: "config",
-  description: "Manage nexus-agents configuration. Subcommands: init, get, set, list, reset, export, import.",
   examples: [
     "nexus-agents config init",
     "nexus-agents config get TIMEOUT_DEFAULTS.cliMs",
@@ -24617,7 +25306,6 @@ var CONFIG_HELP = {
 };
 var RESEARCH_HELP = {
   command: "research",
-  description: "Manage research registry and paper tracking. Subcommands: status, overlap, add, stats, refresh, check, index.",
   examples: [
     "nexus-agents research status",
     "nexus-agents research stats --format=json",
@@ -24632,7 +25320,6 @@ var RESEARCH_HELP = {
 };
 var FITNESS_AUDIT_HELP = {
   command: "fitness-audit",
-  description: "Run CLI orchestration fitness score audit. Target: 90+/100.",
   examples: [
     "nexus-agents fitness-audit",
     "nexus-agents fitness-audit --format=json",
@@ -24649,7 +25336,6 @@ var FITNESS_AUDIT_HELP = {
 };
 var REVIEW_HELP = {
   command: "review",
-  description: "Review a GitHub pull request (dogfooding mode).",
   examples: [
     "nexus-agents review https://github.com/owner/repo/pull/123",
     "nexus-agents review owner/repo#123 --dry-run",
@@ -24678,11 +25364,14 @@ function formatFlag(entry) {
   const defaultSuffix = entry.defaultValue !== void 0 ? ` (default: ${entry.defaultValue})` : "";
   return `  ${entry.flag.padEnd(28)} ${entry.description}${defaultSuffix}`;
 }
+function describe(command) {
+  return getCommandDescription(command) ?? "";
+}
 function formatCommandHelp(command) {
   const entry = COMMAND_HELP.find((e) => e.command === command);
   if (entry === void 0) return void 0;
   const lines = [];
-  lines.push(`nexus-agents ${entry.command} -- ${entry.description}`);
+  lines.push(`nexus-agents ${entry.command} -- ${describe(entry.command)}`);
   lines.push("");
   if (entry.flags !== void 0 && entry.flags.length > 0) {
     lines.push("FLAGS:");