nexus-agents 2.55.1 → 2.57.0

package/dist/cli.js

@@ -12,30 +12,25 @@ import {
   parseFindings,
   sumFindings
 } from "./chunk-6E3NMMEY.js";
-import "./chunk-4FVISCDB.js";
+import "./chunk-6QU4DJYW.js";
 import {
-  setupCommandAsync
-} from "./chunk-XYCS5X3H.js";
-import "./chunk-EKYT4NMD.js";
+  setupCommandAsync,
+  verifyCommand
+} from "./chunk-QNYNQ257.js";
+import "./chunk-QGZBCD2A.js";
 import {
   AuthHandler,
-  CustomExpertDefinitionSchema,
-  DEFAULTS,
   DEFAULT_EXPERTS,
   DEFAULT_SWE_BENCH_CONFIG,
   DEVELOPMENT_POLICY,
   ExpertFactory,
   FeedbackIntegration,
-  MAX_SYSTEM_PROMPT_LENGTH,
   Orchestrator,
   PuppeteerOrchestrator,
   READONLY_POLICY,
   SwarmObserver,
-  VALID_EXPERT_DOMAINS,
-  VALID_EXPERT_TIERS,
   ValidationDashboard,
   WorkflowDefinitionSchema,
-  adaptRoutingConfig,
   addResearchPaper,
   analyzeTools,
   createAgentStages,
@@ -61,7 +56,6 @@ import {
   createTestingExpert,
   createToolObservabilityProxy,
   createToolRateLimiterFactory,
-  defaultConfig,
   detectBackend,
   discoverDeepMind,
   discoverGitHubRepos,
@@ -83,8 +77,6 @@ import {
   generateSwarmVisualization,
   generateSystemSummary,
   getCompletedInstanceIds,
-  getConfig,
-  getConfigManager,
   getDatasetInfo,
   getDefaultTokenPath,
   getEventBusStats,
@@ -103,7 +95,6 @@ import {
   initializeSandbox,
   initializeSica,
   loadAllExternalPacks,
-  loadConfig,
   loadDataset,
   loadSourcesRegistry,
   loadWorkflowFile,
@@ -148,13 +139,12 @@ import {
   setGlobalToolRateLimiterFactory,
   validateArgs,
   validateCommand,
-  validateNexusEnv,
   validateWorkflow,
   wrapInMarkdownFence
-} from "./chunk-KVWHK72T.js";
+} from "./chunk-ZL3IBCH6.js";
 import {
   resolveToken
-} from "./chunk-2SPRLBOS.js";
+} from "./chunk-EZXOJZYE.js";
 import {
   CATEGORY_DISPLAY_NAMES,
   DEFAULT_PR_REVIEW_CONFIG
@@ -170,57 +160,68 @@ import {
   registerConsensusVoteTool,
   shutdownToolMemory,
   validateTimeout
-} from "./chunk-BPMQRYGU.js";
-import "./chunk-R66AWJJ7.js";
+} from "./chunk-BOZ26RIB.js";
+import "./chunk-YU4NABXM.js";
 import {
   loadPapersRegistry,
   loadTechniquesRegistry,
   savePapersRegistry,
   synthesizeResearch
-} from "./chunk-JERFBN73.js";
+} from "./chunk-TC46TRLR.js";
 import {
   classifyTrust,
   createFullGitHubProvider,
   evaluatePolicy,
   parsePRUrl,
   sanitizeInput
-} from "./chunk-FWSTXEG2.js";
-import "./chunk-IOU7F5PH.js";
-import "./chunk-Q5TKQWOI.js";
+} from "./chunk-AFSIP6JH.js";
+import "./chunk-K7EA5OV4.js";
+import "./chunk-V5CGWMYL.js";
 import "./chunk-BC3M4VLP.js";
 import "./chunk-AP2FD37C.js";
 import "./chunk-BQ4YXGGQ.js";
 import "./chunk-ED6VQWNG.js";
 import {
-  BUILT_IN_EXPERTS
-} from "./chunk-GJVHRJO2.js";
-import {
+  CustomExpertDefinitionSchema,
+  MAX_SYSTEM_PROMPT_LENGTH,
+  VALID_EXPERT_DOMAINS,
+  VALID_EXPERT_TIERS,
   VERSION,
+  adaptRoutingConfig,
   closeServer,
   connectTransport,
   createServer,
   doctorCommand,
+  getConfig,
+  getConfigManager,
   initDataDirectories,
-  runDoctor
-} from "./chunk-OC7RMLN2.js";
-import "./chunk-NYNBDP7M.js";
+  loadConfig,
+  runDoctor,
+  validateNexusEnv
+} from "./chunk-Y7CD6AZW.js";
+import {
+  DEFAULTS
+} from "./chunk-H43PABG4.js";
+import "./chunk-NUBSJGQZ.js";
+import "./chunk-GJVHRJO2.js";
+import "./chunk-7Y36JLES.js";
 import {
   MemoryError
-} from "./chunk-3IDJSFWT.js";
+} from "./chunk-TFEFN37P.js";
 import {
   capitalize,
   capitalizeKebab,
   truncateSentence
 } from "./chunk-633WH2ML.js";
-import "./chunk-VKZKC4SM.js";
-import "./chunk-KRIFBGWZ.js";
-import "./chunk-VLVHPC72.js";
+import "./chunk-EDGG3RQE.js";
+import "./chunk-PTGBJFSD.js";
+import "./chunk-ZUWOFHNC.js";
 import {
   createAllAdapters,
   getAvailableClis,
   isRecord
-} from "./chunk-RSUCXOQM.js";
-import "./chunk-W5AJRK4U.js";
+} from "./chunk-SXWZS2V4.js";
+import "./chunk-GMOGKX4E.js";
 import {
   API_TIMEOUTS,
   AgentCapability,
@@ -285,7 +286,7 @@ import {
   toError,
   writeEmptyLine,
   writeLine
-} from "./chunk-UOUJZIKH.js";
+} from "./chunk-R2Y57PM3.js";
 import "./chunk-CLYZ7FWP.js";
 import "./chunk-UP2VWCW5.js";
 
@@ -5836,7 +5837,7 @@ function recordVoteToGitHub(issueNumber, result) {
 async function runVote(options) {
   const threshold = THRESHOLD_MAP[options.threshold ?? "supermajority"] ?? "supermajority";
   const useQuick = options.quick === true;
-  const roles = useQuick ? ["architect", "security", "pm"] : ["architect", "security", "devex", "ai_ml", "pm", "catfish"];
+  const roles = useQuick ? ["architect", "security", "scope_steward"] : ["architect", "security", "devex", "ai_ml", "pm", "catfish", "scope_steward"];
   const start = getTimeProvider().now();
   const requestedTimeoutMs = options.timeoutMs ?? DEFAULT_VOTE_TIMEOUT_MS;
   const { value: timeoutMs, clamped } = validateTimeout(requestedTimeoutMs);
@@ -9258,44 +9259,283 @@ function sanitizeTool(tool) {
 // src/indexer/entrypoint-cli-extractor.ts
 import { SyntaxKind } from "ts-morph";
 import * as path12 from "path";
-function parseHelpTextCommands(helpText) {
-  const commands = [];
-  const lines = helpText.split("\n");
-  let inCommandsSection = false;
-  for (const line of lines) {
-    if (line.trim() === "COMMANDS:") {
-      inCommandsSection = true;
-      continue;
-    }
-    const trimmed = line.trim();
-    if (trimmed.endsWith(":") && trimmed !== "COMMANDS:" && !trimmed.startsWith("-")) {
-      inCommandsSection = false;
-      continue;
-    }
-    if (!inCommandsSection) continue;
-    const match = line.match(/^\s{2}(\S+(?:\s+\S+)?)\s{2,}(.+)$/);
-    if (match !== null) {
-      const cmdPart = match[1];
-      const descriptionPart = match[2];
-      if (cmdPart === void 0 || descriptionPart === void 0) continue;
-      const parts = cmdPart.trim().split(/\s+/);
-      const name = parts[0];
-      if (name === void 0) continue;
-      const subcommand = parts.length > 1 ? parts[1] : void 0;
-      const existing = commands.find((c) => c.name === name);
-      if (existing !== void 0 && subcommand !== void 0) {
-        existing.subcommands.push(subcommand);
-      } else if (existing === void 0) {
-        commands.push({
-          name,
-          description: descriptionPart.trim(),
-          subcommands: subcommand !== void 0 ? [subcommand] : []
-        });
-      }
+
+// src/cli-command-catalog.ts
+var COMMAND_CATALOG = [
+  // ── Essential ────────────────────────────────────────────────────────────
+  {
+    command: "(default)",
+    description: "Start MCP server with stdio transport",
+    audience: "essential"
+  },
+  {
+    command: "hello",
+    description: "Show welcome message and quick start (no API keys needed)",
+    audience: "essential"
+  },
+  {
+    command: "setup",
+    description: "Configure CLI integration (MCP + .rules + data dirs)",
+    audience: "essential"
+  },
+  {
+    command: "verify",
+    description: "Check install health (sqlite, adapters, config)",
+    audience: "essential"
+  },
+  {
+    command: "doctor",
+    description: "Detailed system/adapter health check",
+    audience: "essential"
+  },
+  {
+    command: "config",
+    description: "Manage configuration (init, get, set, list, export, import)",
+    audience: "essential"
+  },
+  {
+    command: "orchestrate",
+    description: "Execute a task via CLI tools (standalone mode)",
+    audience: "essential"
+  },
+  {
+    command: "vote",
+    description: "Run consensus vote on a proposal (5-6 agents)",
+    audience: "essential"
+  },
+  {
+    command: "workflow",
+    description: "Manage and run workflow templates (list, run)",
+    audience: "essential"
+  },
+  {
+    command: "expert",
+    description: "Manage expert agents (list, create, execute)",
+    audience: "essential"
+  },
+  {
+    command: "research",
+    description: "Manage research registry (status, add, stats, refresh)",
+    audience: "essential"
+  },
+  // ── Advanced ─────────────────────────────────────────────────────────────
+  {
+    command: "session",
+    description: "Manage session persistence (list, show, export, delete)",
+    audience: "advanced"
+  },
+  {
+    command: "auth",
+    description: "Manage MCP authentication tokens (init, show, rotate)",
+    audience: "advanced"
+  },
+  {
+    command: "status",
+    description: "At-a-glance project health dashboard",
+    audience: "advanced"
+  },
+  {
+    command: "capabilities",
+    description: "Show model capabilities matrix",
+    audience: "advanced"
+  },
+  {
+    command: "registry",
+    description: "Inspect + refresh the dynamic model registry (doctor / refresh)",
+    audience: "advanced"
+  },
+  {
+    command: "review",
+    description: "Review a GitHub PR (dogfooding helper)",
+    audience: "advanced"
+  },
+  {
+    command: "scaffold",
+    description: "Generate project files from templates",
+    audience: "advanced"
+  },
+  {
+    command: "validate",
+    description: "Run unified validation (doctor + fitness + config)",
+    audience: "advanced"
+  },
+  {
+    command: "index",
+    description: "Generate and manage codebase index",
+    audience: "advanced"
+  },
+  // ── Maintainer (hidden by default) ───────────────────────────────────────
+  {
+    command: "demo",
+    description: "API-free exploration mode (marketing/demo flow)",
+    audience: "maintainer"
+  },
+  {
+    command: "hooks",
+    description: "Claude CLI hook integration commands",
+    audience: "maintainer"
+  },
+  {
+    command: "routing-audit",
+    description: "Debug model routing decisions",
+    audience: "maintainer"
+  },
+  {
+    command: "fitness-audit",
+    description: "Run CLI orchestration fitness score audit",
+    audience: "maintainer"
+  },
+  {
+    command: "system-review",
+    description: "Automated system review (5-phase checklist)",
+    audience: "maintainer"
+  },
+  {
+    command: "sprint",
+    description: "Automated sprint planning from open issues",
+    audience: "maintainer"
+  },
+  {
+    command: "evaluate",
+    description: "Self-evaluation of codebase components",
+    audience: "maintainer"
+  },
+  {
+    command: "issue",
+    description: "Issue template validation and management",
+    audience: "maintainer"
+  },
+  {
+    command: "validation",
+    description: "Learning validation dashboard",
+    audience: "maintainer"
+  },
+  {
+    command: "learning-metrics",
+    description: "Aggregated learning metrics dashboard",
+    audience: "maintainer"
+  },
+  {
+    command: "swe-bench",
+    description: "Run SWE-bench evaluation benchmark",
+    audience: "maintainer"
+  },
+  {
+    command: "atbench",
+    description: "Run ATBench trajectory-safety evaluation",
+    audience: "maintainer"
+  },
+  {
+    command: "visualize",
+    description: "Generate Mermaid diagrams and ASCII dashboards",
+    audience: "maintainer"
+  },
+  {
+    command: "health",
+    description: "Swarm health metrics dashboard",
+    audience: "maintainer"
+  },
+  {
+    command: "release-notes",
+    description: "Generate release notes from git commits",
+    audience: "maintainer"
+  },
+  {
+    command: "release-validate",
+    description: "Run expert swarm validation for releases",
+    audience: "maintainer"
+  },
+  {
+    command: "release-announce",
+    description: "Generate release announcements (blog, social)",
+    audience: "maintainer"
+  },
+  // ── Internal (hidden everywhere; here for extractor/index completeness) ──
+  {
+    command: "server",
+    // Synonym for the no-arg invocation — `nexus-agents` and
+    // `nexus-agents server` both run `handleServerCommand`. Listed here for
+    // extractor completeness; humans see `(default)` in --help.
+    description: "Start MCP server with stdio transport (explicit form)",
+    audience: "internal"
+  },
+  {
+    command: "e2e-eval",
+    description: "E2E evaluation scenario runner (dev loop)",
+    audience: "internal"
+  },
+  {
+    command: "memory-benchmark",
+    description: "Memory-system benchmark runner (dev loop)",
+    audience: "internal"
+  },
+  {
+    command: "memory-eval",
+    description: "Comparative memory evaluation benchmark (dev loop)",
+    audience: "internal"
+  },
+  {
+    command: "routing-ab",
+    description: "A/B comparison of routing strategies (dev loop)",
+    audience: "internal"
+  },
+  {
+    command: "scenario",
+    description: "Execute a named scenario from the testing framework",
+    audience: "internal"
+  },
+  {
+    command: "warm-up",
+    description: "Warm the model/adapter caches before a run",
+    audience: "internal"
+  }
+];
+function filterCatalog(showAll) {
+  const visible = COMMAND_CATALOG.filter((e) => e.audience !== "internal");
+  if (showAll) return visible;
+  return visible.filter((e) => e.audience !== "maintainer");
+}
+function catalogForExtractors() {
+  return COMMAND_CATALOG.filter((e) => e.command !== "(default)");
+}
+function groupByAudience(entries) {
+  const groups = /* @__PURE__ */ new Map();
+  for (const entry of entries) {
+    const existing = groups.get(entry.audience) ?? [];
+    existing.push(entry);
+    groups.set(entry.audience, existing);
+  }
+  return groups;
+}
+var AUDIENCE_HEADINGS = {
+  essential: "Essential \u2014 install, configure, run",
+  advanced: "Advanced \u2014 day-to-day extras",
+  maintainer: "Maintainer \u2014 benchmarks, releases, deep diagnostics",
+  // Never rendered (filterCatalog strips internal before renderCommandsSection
+  // iterates), but required by the Record<CommandAudience, string> contract.
+  internal: "Internal \u2014 dev/eval loops (hidden from --help)"
+};
+function renderCommandsSection(showAll) {
+  const filtered = filterCatalog(showAll);
+  const groups = groupByAudience(filtered);
+  const lines = [];
+  const order = showAll ? ["essential", "advanced", "maintainer"] : ["essential", "advanced"];
+  for (const audience of order) {
+    const entries = groups.get(audience);
+    if (entries === void 0 || entries.length === 0) continue;
+    lines.push(`  ${AUDIENCE_HEADINGS[audience]}`);
+    for (const entry of entries) {
+      lines.push(`    ${entry.command.padEnd(16)} ${entry.description}`);
     }
+    lines.push("");
   }
-  return commands;
+  if (!showAll) {
+    lines.push("  Run with --all to show maintainer commands (benchmarks, release tooling).");
+  }
+  return lines.join("\n").replace(/\n+$/, "");
 }
+
+// src/indexer/entrypoint-cli-extractor.ts
 function extractCliOptions(sourceFile) {
   const options = /* @__PURE__ */ new Map();
   const configVar = sourceFile.getVariableDeclaration("PARSE_ARGS_CONFIG");
@@ -9389,46 +9629,54 @@ function getCommandOptions(name, cliOptions) {
   }
   return cmdOptions;
 }
-function extractCliCommands(project, packageRoot, cliCommandsPath, cliTypesPath) {
-  const commands = [];
+function buildCommandSpec(entry, ctx) {
+  const handlerName = `handle${toPascalCase(entry.command)}Command`;
+  const handlerFunc = ctx.commandsFile.getFunction(handlerName);
+  const sourceLine = handlerFunc?.getStartLineNumber() ?? 1;
+  if (handlerFunc === void 0 && ctx.warnings !== void 0) {
+    ctx.warnings.push(
+      `CLI extraction: catalog entry "${entry.command}" has no matching ${handlerName} function in ${ctx.cliCommandsPath}. Check naming drift.`
+    );
+  }
+  const cmdOptions = getCommandOptions(entry.command, ctx.cliOptions);
+  const cmdSpec = {
+    name: entry.command,
+    description: entry.description,
+    source_file: ctx.relativePath,
+    source_line: sourceLine
+  };
+  if (cmdOptions.length > 0) {
+    cmdSpec.options = cmdOptions;
+  }
+  return cmdSpec;
+}
+function extractCliCommands(project, packageRoot, cliCommandsPath, cliTypesPath, warnings) {
   const typesFullPath = path12.join(packageRoot, cliTypesPath);
   const typesFile = project.getSourceFile(typesFullPath);
-  let helpTextCommands = [];
-  let cliOptions = /* @__PURE__ */ new Map();
-  if (typesFile !== void 0) {
-    const helpTextVar = typesFile.getVariableDeclaration("HELP_TEXT");
-    if (helpTextVar !== void 0) {
-      const helpText = helpTextVar.getInitializer()?.getText() ?? "";
-      const cleanText = helpText.slice(1, -1).replace(/^\s*\n/, "").replace(/\n\s*$/, "");
-      helpTextCommands = parseHelpTextCommands(cleanText);
-    }
-    cliOptions = extractCliOptions(typesFile);
+  if (typesFile === void 0 && warnings !== void 0) {
+    warnings.push(
+      `CLI extraction: types file not loaded (${typesFullPath}). PARSE_ARGS_CONFIG options will be missing from the manifest.`
+    );
   }
+  const cliOptions = typesFile !== void 0 ? extractCliOptions(typesFile) : /* @__PURE__ */ new Map();
   const commandsFullPath = path12.join(packageRoot, cliCommandsPath);
   const commandsFile = project.getSourceFile(commandsFullPath);
-  if (commandsFile === void 0) return commands;
-  const relativePath = path12.relative(process.cwd(), commandsFullPath);
-  for (const cmdMeta of helpTextCommands) {
-    if (cmdMeta.name === "(default)") continue;
-    const handlerName = `handle${toPascalCase(cmdMeta.name)}Command`;
-    const handlerFunc = commandsFile.getFunction(handlerName);
-    const sourceLine = handlerFunc?.getStartLineNumber() ?? 1;
-    const cmdOptions = getCommandOptions(cmdMeta.name, cliOptions);
-    const cmdSpec = {
-      name: cmdMeta.name,
-      description: cmdMeta.description,
-      source_file: relativePath,
-      source_line: sourceLine
-    };
-    if (cmdMeta.subcommands.length > 0) {
-      cmdSpec.subcommands = cmdMeta.subcommands;
-    }
-    if (cmdOptions.length > 0) {
-      cmdSpec.options = cmdOptions;
+  if (commandsFile === void 0) {
+    if (warnings !== void 0) {
+      warnings.push(
+        `CLI extraction: commands file not loaded (${commandsFullPath}). Returning zero commands.`
+      );
     }
-    commands.push(cmdSpec);
+    return [];
   }
-  return commands;
+  const ctx = {
+    commandsFile,
+    relativePath: path12.relative(process.cwd(), commandsFullPath),
+    cliOptions,
+    cliCommandsPath,
+    ...warnings !== void 0 && { warnings }
+  };
+  return catalogForExtractors().map((entry) => buildCommandSpec(entry, ctx));
 }
 
 // src/indexer/entrypoint-mcp-extractor.ts
@@ -9474,10 +9722,15 @@ function extractZodParameters(schemaObj) {
   }
   return params;
 }
-function extractMcpTools(project, packageRoot, mcpToolsPath) {
+function extractMcpTools(project, packageRoot, mcpToolsPath, warnings) {
   const tools = [];
   const toolsDir = path13.join(packageRoot, mcpToolsPath);
   const toolFiles = project.getSourceFiles(`${toolsDir}/*.ts`);
+  if (toolFiles.length === 0 && warnings !== void 0) {
+    warnings.push(
+      `MCP tool extraction: glob "${toolsDir}/*.ts" matched zero files. Check that the path exists and is included in the ts-morph project.`
+    );
+  }
   for (const sourceFile of toolFiles) {
     const filePath = sourceFile.getFilePath();
     const fileName = path13.basename(filePath);
@@ -9499,7 +9752,11 @@ function extractToolsFromFile(sourceFile, relativePath) {
     if (args.length < 2) continue;
     const nameArg = args[0];
     if (nameArg === void 0) continue;
-    const toolName = nameArg.getText().replace(/['"]/g, "");
+    const nameKind = nameArg.getKind();
+    if (nameKind !== SyntaxKind2.StringLiteral && nameKind !== SyntaxKind2.NoSubstitutionTemplateLiteral) {
+      continue;
+    }
+    const toolName = nameArg.getText().replace(/['"`]/g, "");
     const { description, schemaArg } = extractToolMeta(callText, args, sourceFile);
     let parameters = [];
     if (schemaArg !== void 0) {
@@ -9591,6 +9848,11 @@ function createProject(opts) {
   project.addSourceFilesAtPaths([
     path14.join(opts.packageRoot, opts.cliCommandsPath),
     path14.join(opts.packageRoot, "src/cli-types.ts"),
+    // HELP_TEXT was extracted to cli-help-text.ts in #293 (Jan 2026) and
+    // cli-types.ts now only re-exports it. The extractor reads it via AST,
+    // so we have to load the defining file — a bare re-export isn't enough.
+    // Without this line the CLI command list silently came back empty.
+    path14.join(opts.packageRoot, "src/cli-help-text.ts"),
     path14.join(opts.packageRoot, opts.mcpToolsPath, "*.ts")
   ]);
   return project;
@@ -9605,9 +9867,10 @@ function extractEntrypoints(options = {}) {
       project,
       opts.packageRoot,
       opts.cliCommandsPath,
-      "src/cli-types.ts"
+      "src/cli-types.ts",
+      warnings
     );
-    const mcpTools = extractMcpTools(project, opts.packageRoot, opts.mcpToolsPath);
+    const mcpTools = extractMcpTools(project, opts.packageRoot, opts.mcpToolsPath, warnings);
     const finalCommands = opts.sanitize ? cliCommands.map(sanitizeCommand) : cliCommands;
     const finalTools = opts.sanitize ? mcpTools.map(sanitizeTool) : mcpTools;
     const manifest = {
@@ -10409,182 +10672,6 @@ function parseValidationArgs(positionals, format, verbose) {
   return options;
 }
 
-// src/cli/verify-command.ts
-function checkNodeVersion() {
-  const version = process.version;
-  const major = parseInt(version.slice(1).split(".")[0] ?? "0", 10);
-  if (major >= 22) {
-    return {
-      name: "Node.js Version",
-      passed: true,
-      message: `${version} (LTS)`
-    };
-  }
-  if (major >= 18) {
-    return {
-      name: "Node.js Version",
-      passed: true,
-      message: `${version} (supported, recommend 22.x LTS)`
-    };
-  }
-  return {
-    name: "Node.js Version",
-    passed: false,
-    message: `${version} (unsupported)`,
-    fix: "Install Node.js 22.x LTS from https://nodejs.org"
-  };
-}
-function checkPackageExports() {
-  try {
-    const hasVersion = typeof VERSION === "string" && VERSION.length > 0;
-    const hasConfig = typeof defaultConfig === "object";
-    const hasBuiltInExperts = typeof BUILT_IN_EXPERTS === "object";
-    if (hasVersion && hasConfig && hasBuiltInExperts) {
-      return {
-        name: "Package Exports",
-        passed: true,
-        message: "All core modules accessible"
-      };
-    }
-    return {
-      name: "Package Exports",
-      passed: false,
-      message: "Some modules failed to load",
-      fix: "Try reinstalling: npm install -g nexus-agents"
-    };
-  } catch {
-    return {
-      name: "Package Exports",
-      passed: false,
-      message: "Failed to load core modules",
-      fix: "Try reinstalling: npm install -g nexus-agents"
-    };
-  }
-}
-function checkConfigLoading() {
-  try {
-    const hasModels = typeof defaultConfig.models === "object";
-    const hasSecurity = typeof defaultConfig.security === "object";
-    if (hasModels && hasSecurity) {
-      return {
-        name: "Configuration",
-        passed: true,
-        message: "Default config accessible"
-      };
-    }
-    return {
-      name: "Configuration",
-      passed: true,
-      // Config errors are not fatal for verification
-      message: "Using default configuration"
-    };
-  } catch {
-    return {
-      name: "Configuration",
-      passed: true,
-      // Still works with defaults
-      message: "Using default configuration"
-    };
-  }
-}
-function checkExpertSystem() {
-  const expertTypes = Object.keys(BUILT_IN_EXPERTS);
-  const count = expertTypes.length;
-  if (count >= 5) {
-    return {
-      name: "Expert System",
-      passed: true,
-      message: `${String(count)} expert types available`
-    };
-  }
-  return {
-    name: "Expert System",
-    passed: false,
-    message: "Expert types not loaded",
-    fix: "Try reinstalling: npm install -g nexus-agents"
-  };
-}
-function runVerify() {
-  const time = getTimeProvider();
-  const startTime = time.now();
-  const checks = [
-    checkNodeVersion(),
-    checkPackageExports(),
-    checkConfigLoading(),
-    checkExpertSystem()
-  ];
-  const allPassed = checks.every((c) => c.passed);
-  const durationMs = time.now() - startTime;
-  return Promise.resolve({
-    version: VERSION,
-    nodeVersion: process.version,
-    checks,
-    allPassed,
-    durationMs
-  });
-}
-function formatCheck(check) {
-  const symbol = check.passed ? `${colors.green}${symbols.check}${colors.reset}` : `${colors.red}${symbols.cross}${colors.reset}`;
-  let line = `  ${symbol} ${check.name}: ${check.message}`;
-  if (!check.passed && check.fix !== void 0) {
-    line += `
-     ${colors.dim}Fix: ${check.fix}${colors.reset}`;
-  }
-  return line;
-}
-function printVerifyResult(result, verbose) {
-  process.stdout.write("\n");
-  process.stdout.write(`${colors.bold}nexus-agents verify${colors.reset}
-`);
-  process.stdout.write("===================\n");
-  process.stdout.write("\n");
-  process.stdout.write(`Version: ${result.version}
-`);
-  process.stdout.write(`Node.js: ${result.nodeVersion}
-`);
-  process.stdout.write("\n");
-  process.stdout.write(`${colors.cyan}Running checks...${colors.reset}
-`);
-  process.stdout.write("\n");
-  for (const check of result.checks) {
-    process.stdout.write(formatCheck(check) + "\n");
-  }
-  process.stdout.write("\n");
-  if (result.allPassed) {
-    process.stdout.write(
-      `${colors.green}${colors.bold}Installation verified successfully!${colors.reset}
-`
-    );
-    process.stdout.write("\n");
-    process.stdout.write(`${colors.cyan}Next steps:${colors.reset}
-`);
-    process.stdout.write('  1. Run "nexus-agents doctor" to check external CLI integrations\n');
-    process.stdout.write(
-      '  2. Run "nexus-agents review --setup" to configure GitHub integration\n'
-    );
-    process.stdout.write('  3. Try "nexus-agents --help" for all available commands\n');
-  } else {
-    const failedCount = result.checks.filter((c) => !c.passed).length;
-    process.stdout.write(
-      `${colors.red}${colors.bold}Verification failed: ${String(failedCount)} issue(s) found${colors.reset}
-`
-    );
-    process.stdout.write("\n");
-    process.stdout.write("Please fix the issues above and try again.\n");
-  }
-  process.stdout.write("\n");
-  if (verbose) {
-    process.stdout.write(`${colors.dim}Duration: ${String(result.durationMs)}ms${colors.reset}
-`);
-    process.stdout.write("\n");
-  }
-}
-async function verifyCommand(options) {
-  const result = await runVerify();
-  printVerifyResult(result, options.verbose);
-  return result.allPassed ? 0 : 1;
-}
-
 // src/cli/swe-bench-command.ts
 import * as os2 from "os";
 import * as path18 from "path";
@@ -14276,9 +14363,15 @@ var FitnessScoreCalculator = class {
   }
   /**
    * Check explicit behavior: penalize hidden/magic behavior.
-   * TODO: This dimension lacks strong filesystem signals. Currently checks
-   * for NEXUS_ALLOW_MOCK_ORCHESTRATION guard and magic routing patterns.
-   * Future: add AST-based detection of implicit fallbacks.
+   *
+   * Implementation is intentionally filesystem-signal-based (no AST parse).
+   * The `NEXUS_ALLOW_MOCK_ORCHESTRATION` guard and magic-routing pattern
+   * grep capture the observable failure modes that historically slipped
+   * past review. AST-based detection of implicit fallbacks was considered
+   * but not pursued — it would significantly widen this function's
+   * footprint and the filesystem signals already catch the recurring
+   * regressions. Revisit only if a new class of hidden-behavior bug
+   * surfaces that this grep-over-source approach can't catch.
    */
   checkExplicitBehavior() {
     const findings = [];
@@ -17294,6 +17387,15 @@ EXAMPLES:
 
 For more information, visit: https://github.com/williamzujkowski/nexus-agents
 `.trim();
+var COMMANDS_BLOCK_RE = /COMMANDS:\n([\s\S]*?)\n\nOPTIONS:/;
+function renderHelp(opts) {
+  if (opts.all) return HELP_TEXT;
+  const replacement = renderCommandsSection(false);
+  return HELP_TEXT.replace(COMMANDS_BLOCK_RE, `COMMANDS:
+${replacement}
+
+OPTIONS:`);
+}
 
 // src/cli-types.ts
 var EXIT_CODES = {
@@ -17322,6 +17424,11 @@ var PARSE_ARGS_CONFIG = {
       type: "boolean",
       default: false
     },
+    // Tiered --help output (Issue #2135): `--help --all` unhides maintainer commands
+    all: {
+      type: "boolean",
+      default: false
+    },
     mode: {
       type: "string",
       short: "m",
@@ -17536,6 +17643,14 @@ var PARSE_ARGS_CONFIG = {
     deep: {
       type: "boolean",
       default: false
+    },
+    // Registry command options (#2179)
+    json: {
+      type: "boolean",
+      default: false
+    },
+    source: {
+      type: "string"
     }
   },
   allowPositionals: true,
@@ -17586,7 +17701,8 @@ function isValidCommand(value) {
     "routing-ab",
     "memory-eval",
     "health",
-    "validate"
+    "validate",
+    "registry"
   ];
   return validCommands.includes(value);
 }
@@ -19884,12 +20000,14 @@ function setupShutdownHandlers(cleanup, logger17) {
       process.exit(EXIT_CODES.SHUTDOWN_ERROR);
     }
   };
-  process.on("SIGINT", () => {
-    void handleShutdown("SIGINT");
-  });
-  process.on("SIGTERM", () => {
-    void handleShutdown("SIGTERM");
-  });
+  const onSignal = (signal) => () => {
+    handleShutdown(signal).catch((err2) => {
+      logger17.error("Shutdown handler crashed", err2 instanceof Error ? err2 : new Error(String(err2)));
+      process.exit(EXIT_CODES.SHUTDOWN_ERROR);
+    });
+  };
+  process.on("SIGINT", onSignal("SIGINT"));
+  process.on("SIGTERM", onSignal("SIGTERM"));
   process.on("uncaughtException", (error) => {
     logger17.error("Uncaught exception", error);
     process.exit(EXIT_CODES.SERVER_START_FAILED);
@@ -20085,7 +20203,7 @@ async function initializeSubsystems(config, logger17) {
   await initializeAndLogSandbox(serverLogger, config.security?.sandbox);
   const policyFirewall = logSecurityConfig(serverLogger, config);
   const auditLogger = initializeAuditLogger(config.security, serverLogger);
-  const authInit = initializeAuth(config, serverLogger);
+  initializeAuth(config, serverLogger);
   await initializeAndRegisterTools(
     server,
     serverLogger,
@@ -20093,8 +20211,9 @@ async function initializeSubsystems(config, logger17) {
     config,
     feedbackResult.feedbackIntegration
   );
-  return { server, serverLogger, observer, eventBusBridge, policyFirewall, auditLogger, authInit };
+  return { server, serverLogger, observer, eventBusBridge, auditLogger };
 }
+var SERVER_STARTUP_TIMEOUT_MS = 3e4;
 async function startServer(verbose, mode, modeWasExplicit = false, orchestratorOptions) {
   const logger17 = createLogger({ component: "cli" });
   if (verbose) logger17.setLevel("debug");
@@ -20103,6 +20222,13 @@ async function startServer(verbose, mode, modeWasExplicit = false, orchestratorO
     await startOrchestratorMode(orchestratorOptions ?? { verbose });
     return;
   }
+  const startupWatchdog = setTimeout(() => {
+    logger17.error(
+      `Server startup exceeded ${String(SERVER_STARTUP_TIMEOUT_MS)}ms \u2014 aborting. Common causes: hung config load, blocked subsystem init, stdio transport stall.`
+    );
+    process.exit(EXIT_CODES.SERVER_START_FAILED);
+  }, SERVER_STARTUP_TIMEOUT_MS);
+  startupWatchdog.unref();
   const detectionResult = detectMode({ explicitMode: modeWasExplicit ? mode : void 0 });
   logStartupInfo(logger17, detectionResult, verbose);
   const configResult = loadAndLogConfig(logger17);
@@ -20127,6 +20253,7 @@ async function startServer(verbose, mode, modeWasExplicit = false, orchestratorO
     auditLogger
   });
   setupShutdownHandlers(cleanup, logger17);
+  clearTimeout(startupWatchdog);
   logger17.debug("Server running, waiting for requests...");
 }
 
@@ -20158,6 +20285,11 @@ function isValidIndexFormat(value) {
 function isValidResearchFormat(value) {
   return value === "table" || value === "json";
 }
+function parsePositiveInt(arg, defaultVal) {
+  if (arg === void 0) return defaultVal;
+  const parsed = parseInt(arg, 10);
+  return Number.isNaN(parsed) || parsed <= 0 ? defaultVal : parsed;
+}
 
 // src/cli-commands-usage.ts
 function printWorkflowRunUsage() {
@@ -20504,6 +20636,32 @@ async function handleResearchCommand(args) {
     process.exit(EXIT_CODES.SERVER_START_FAILED);
   }
 }
+async function handleRegistryCommand(args) {
+  const { registryCommand, isValidRegistrySubcommand, formatRegistryUsage } = await import("./registry-command-S46JJ2SX.js");
+  const subcommand = args.subcommand;
+  if (!isValidRegistrySubcommand(subcommand)) {
+    process.stdout.write(`${formatRegistryUsage()}
+`);
+    process.exit(EXIT_CODES.INVALID_ARGS);
+  }
+  const source = typeof args.options.source === "string" ? args.options.source : void 0;
+  const options = {
+    json: args.options.json === true,
+    dryRun: args.options.dryRun,
+    ...source !== void 0 ? { source } : {}
+  };
+  try {
+    const result = await registryCommand(subcommand, options);
+    process.stdout.write(`${result.text}
+`);
+    process.exit(result.exitCode === 0 ? EXIT_CODES.SUCCESS : EXIT_CODES.SERVER_START_FAILED);
+  } catch (error) {
+    const message = getErrorMessage(error);
+    process.stdout.write(`Error: ${message}
+`);
+    process.exit(EXIT_CODES.SERVER_START_FAILED);
+  }
+}
 function handleValidationCommand(args) {
   const options = parseValidationArgs(args.positionals, args.options.format, args.options.verbose);
   const exitCode = validationDashboardCommand(options);
@@ -20527,7 +20685,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-RKMOZSIS.js");
+    const { runDeepDiagnostics: runDeepDiagnostics2, formatDeepDiagnostics: formatDeepDiagnostics2 } = await import("./doctor-deep-VN6KMUCG.js");
     const diag = runDeepDiagnostics2();
     process.stdout.write(formatDeepDiagnostics2(diag) + "\n");
   }
@@ -20556,7 +20714,7 @@ async function handleSetupCommandAsync(args) {
   process.exit(exitCode === 0 ? EXIT_CODES.SUCCESS : EXIT_CODES.SERVER_START_FAILED);
 }
 async function runCustomApiSetup(args) {
-  const { configureCustomApi } = await import("./setup-custom-api-XAWKRDWV.js");
+  const { configureCustomApi } = await import("./setup-custom-api-CSB26HWD.js");
   const baseUrl = args.options.customApi;
   if (baseUrl === void 0) return EXIT_CODES.SERVER_START_FAILED;
   const input = {
@@ -20716,25 +20874,19 @@ function handleWarmUpCommand(_args) {
   process.exit(EXIT_CODES.SUCCESS);
 }
 function handleE2EEvalCommand(args) {
-  const countArg = args.positionals[1];
-  const taskCount = countArg !== void 0 ? parseInt(countArg, 10) : 50;
-  const count = Number.isNaN(taskCount) || taskCount <= 0 ? 50 : taskCount;
+  const count = parsePositiveInt(args.positionals[1], 50);
   const result = runE2EEval({ taskCount: count });
   process.stdout.write(formatE2EEvalResult(result) + "\n");
   process.exit(result.passed ? EXIT_CODES.SUCCESS : 1);
 }
 function handleRoutingABCommand(args) {
-  const countArg = args.positionals[1];
-  const taskCount = countArg !== void 0 ? parseInt(countArg, 10) : 30;
-  const count = Number.isNaN(taskCount) || taskCount <= 0 ? 30 : taskCount;
+  const count = parsePositiveInt(args.positionals[1], 30);
   const result = runRoutingAB({ taskCount: count });
   process.stdout.write(formatABReport(result) + "\n");
   process.exit(EXIT_CODES.SUCCESS);
 }
 function handleMemoryEvalCommand(args) {
-  const sizeArg = args.positionals[1];
-  const size = sizeArg !== void 0 ? parseInt(sizeArg, 10) : 50;
-  const count = Number.isNaN(size) || size <= 0 ? 50 : size;
+  const count = parsePositiveInt(args.positionals[1], 50);
   const result = runMemoryEval(count);
   process.stdout.write(formatMemoryEvalReport(result) + "\n");
   process.exit(EXIT_CODES.SUCCESS);
@@ -22614,8 +22766,9 @@ async function handleValidateCommand(args) {
 }
 
 // src/cli-commands.ts
-function printHelp() {
-  process.stdout.write(HELP_TEXT + "\n");
+function printHelp(args) {
+  const all = args?.options.all ?? false;
+  process.stdout.write(renderHelp({ all }) + "\n");
 }
 function printVersion() {
   process.stdout.write(`nexus-agents v${VERSION}
@@ -22652,7 +22805,7 @@ var SYNC_COMMAND_HANDLERS = {
 };
 function handleSyncCommand(args) {
   if (args.command === "help") {
-    printHelp();
+    printHelp(args);
     process.exit(EXIT_CODES.SUCCESS);
   }
   if (args.command === "version") {
@@ -22677,6 +22830,7 @@ var ASYNC_COMMAND_HANDLERS = {
   vote: handleVoteCommand,
   index: handleIndexCommand2,
   research: handleResearchCommand,
+  registry: handleRegistryCommand,
   "swe-bench": handleSweBenchCommand,
   atbench: handleAtbenchCommand,
   hooks: handleHooksCommand,
@@ -23067,6 +23221,7 @@ function buildOptions(values) {
     version: values.version,
     verbose: values.verbose,
     interactive: values.interactive,
+    all: values.all,
     mode: detectionResult.mode,
     force: values.force,
     format: values.format,
@@ -23079,6 +23234,8 @@ function buildOptions(values) {
     quick: values.quick,
     mock: values.mock,
     deep: values.deep,
+    json: values.json,
+    ...values.source !== void 0 && { source: values.source },
     ...values.output !== void 0 && { output: values.output },
     ...values.input !== void 0 && { input: values.input },
     ...buildOrchestrateOptions(values),