@evomap/evolver 1.92.0 → 1.94.0

package/CONTRIBUTING.md

@@ -11,6 +11,18 @@ Submit PRs with clear intent and scope.
 
 ### Engineering conventions
 
+- **Evolver is the upstream governance source for EvoX harness/evolver behavior.**
+  Any PR that changes harness/evaluator/self-evolution surfaces (GEP schemas,
+  prompt/selector/mutation/solidify/candidate/evaluator logic, evolve pipeline,
+  adapter execution bridge, proxy routing/trace, bundled GEP assets, or the EvoX
+  bridge contract) must fill the `## Harness/evaluator governance` PR-template
+  packet. The required packet documents the whitelisted surface, downstream EvoX
+  impact, rollout-local scope, promotion boundary, evaluator mismatch sets,
+  non-regression evidence, fix severity, owner approval, security boundary,
+  rollback, and the two hard denials: `Live promotion: no` and
+  `Autonomous evaluator self-editing: no`. `scripts/harness-governance-check.js`
+  enforces this on PRs.
+
 - **Spawn child CLIs as `node <entry.js>` — never via a `.cmd` shim, npm symlink, or bare command name.** When launching a harness/tool subprocess (claude-code, openclaw, codex, ...), resolve the JS entry behind the launcher and hand it to `node` directly. Two reasons:
   1. On Windows, `child_process.spawn` without `shell:true` on a `.cmd`/`.bat` throws `EINVAL` since the CVE-2024-27980 fix (Node >=18.20.2 / 20.12.2 / 21.7.3) — this silently broke the auto-exec bridge on Windows.
   2. Across platforms, shims/wrappers can emit warnings or silently exit on some machines. `node <entry>` is zero-shell, deterministic, and passes args via argv (no shell-injection surface).

package/README.ja-JP.md

@@ -1,6 +1,6 @@
 # 🧬 Evolver
 
-[![GitHub stars](https://img.shields.io/badge/Stars-8.9k-2b3137?logo=github&logoColor=white)](https://github.com/EvoMap/evolver/stargazers)
+[![GitHub stars](https://img.shields.io/badge/Stars-9k-2b3137?logo=github&logoColor=white)](https://github.com/EvoMap/evolver/stargazers)
 [![License: GPL-3.0](https://img.shields.io/badge/License-GPL--3.0-blue.svg)](https://opensource.org/licenses/GPL-3.0)
 [![Node.js >= 18](https://img.shields.io/badge/Node.js-%3E%3D%2018-green.svg)](https://nodejs.org/)
 [![npm downloads](https://img.shields.io/npm/dm/@evomap/evolver.svg)](https://www.npmjs.com/package/@evomap/evolver)

package/README.ko-KR.md

@@ -1,6 +1,6 @@
 # 🧬 Evolver
 
-[![GitHub stars](https://img.shields.io/badge/Stars-8.9k-2b3137?logo=github&logoColor=white)](https://github.com/EvoMap/evolver/stargazers)
+[![GitHub stars](https://img.shields.io/badge/Stars-9k-2b3137?logo=github&logoColor=white)](https://github.com/EvoMap/evolver/stargazers)
 [![License: GPL-3.0](https://img.shields.io/badge/License-GPL--3.0-blue.svg)](https://opensource.org/licenses/GPL-3.0)
 [![Node.js >= 18](https://img.shields.io/badge/Node.js-%3E%3D%2018-green.svg)](https://nodejs.org/)
 [![npm downloads](https://img.shields.io/npm/dm/@evomap/evolver.svg)](https://www.npmjs.com/package/@evomap/evolver)

package/README.md

@@ -1,12 +1,20 @@
-# 🧬 Evolver
-
-[![GitHub stars](https://img.shields.io/badge/Stars-8.9k-2b3137?logo=github&logoColor=white)](https://github.com/EvoMap/evolver/stargazers)
-[![License: GPL-3.0](https://img.shields.io/badge/License-GPL--3.0-blue.svg)](https://opensource.org/licenses/GPL-3.0)
-[![Node.js >= 18](https://img.shields.io/badge/Node.js-%3E%3D%2018-green.svg)](https://nodejs.org/)
-[![npm downloads](https://img.shields.io/npm/dm/@evomap/evolver.svg)](https://www.npmjs.com/package/@evomap/evolver)
-[![arXiv](https://img.shields.io/badge/arXiv-2604.15097-b31b1b.svg)](https://arxiv.org/abs/2604.15097)
-
-![Evolver Cover](assets/cover.png)
+<p align="center">
+  <img src="assets/logo.png" alt="Evolver" width="96" height="96" />
+</p>
+
+<h1 align="center">Evolver — Agent Self-Evolving Engine</h1>
+
+<p align="center">
+  <a href="https://trendshift.io/repositories/26015?utm_source=repository-badge&amp;utm_medium=badge&amp;utm_campaign=badge-repository-26015" target="_blank" rel="noopener noreferrer"><img src="https://trendshift.io/api/badge/repositories/26015" alt="EvoMap%2Fevolver | Trendshift" width="250" height="55"/></a>
+</p>
+
+<p align="center">
+  <a href="https://github.com/EvoMap/evolver/stargazers"><img src="https://img.shields.io/badge/Stars-9k-2b3137?logo=github&amp;logoColor=white" alt="GitHub stars"/></a>
+  <a href="https://opensource.org/licenses/GPL-3.0"><img src="https://img.shields.io/badge/License-GPL--3.0-blue.svg" alt="License: GPL-3.0"/></a>
+  <a href="https://nodejs.org/"><img src="https://img.shields.io/badge/Node.js-%3E%3D%2018-green.svg" alt="Node.js &gt;= 18"/></a>
+  <a href="https://www.npmjs.com/package/@evomap/evolver"><img src="https://img.shields.io/npm/dm/@evomap/evolver.svg" alt="npm downloads"/></a>
+  <a href="https://arxiv.org/abs/2604.15097"><img src="https://img.shields.io/badge/arXiv-2604.15097-b31b1b.svg" alt="arXiv"/></a>
+</p>
 
 **[evomap.ai](https://evomap.ai)** | [Documentation](https://evomap.ai/wiki) | [Chinese / 中文文档](README.zh-CN.md) | [Japanese / 日本語ドキュメント](README.ja-JP.md) | [Korean / 한국어 문서](README.ko-KR.md) | [GitHub](https://github.com/EvoMap/evolver) | [Releases](https://github.com/EvoMap/evolver/releases)
 

package/README.zh-CN.md

@@ -1,6 +1,6 @@
 # 🧬 Evolver
 
-[![GitHub stars](https://img.shields.io/badge/Stars-8.9k-2b3137?logo=github&logoColor=white)](https://github.com/EvoMap/evolver/stargazers)
+[![GitHub stars](https://img.shields.io/badge/Stars-9k-2b3137?logo=github&logoColor=white)](https://github.com/EvoMap/evolver/stargazers)
 [![License: GPL-3.0](https://img.shields.io/badge/License-GPL--3.0-blue.svg)](https://opensource.org/licenses/GPL-3.0)
 [![Node.js >= 18](https://img.shields.io/badge/Node.js-%3E%3D%2018-green.svg)](https://nodejs.org/)
 [![npm downloads](https://img.shields.io/npm/dm/@evomap/evolver.svg)](https://www.npmjs.com/package/@evomap/evolver)

package/SKILL.md

@@ -66,11 +66,11 @@ metadata:
     reads:
       - "~/.evolver/settings.json (Proxy address discovery)"
       - "~/.evomap/node_id (node identity)"
-      - "assets/gep/* (GEP assets)"
-      - "memory/* (evolution memory)"
+      - "$EVOLVER_HOME/gep/* (runtime GEP assets)"
+      - "$EVOLVER_HOME/memory/* (runtime evolution memory)"
     writes:
-      - "assets/gep/* (genes, capsules, events)"
-      - "memory/* (memory graph, narrative, reflection)"
+      - "$EVOLVER_HOME/gep/* (runtime genes, capsules, events)"
+      - "$EVOLVER_HOME/memory/* (runtime memory graph, narrative, reflection)"
       - "src/** (evolved code, only during solidify)"
 ---
 
@@ -346,10 +346,10 @@ node index.js --review
 
 ## GEP Protocol (Auditable Evolution)
 
-Local asset store:
-- `assets/gep/genes.json` -- reusable Gene definitions
-- `assets/gep/capsules.json` -- success capsules
-- `assets/gep/events.jsonl` -- append-only evolution events
+Local runtime asset store (created and maintained by Evolver; these mutable runtime files are not bundled in the published Skill package):
+- `$EVOLVER_HOME/gep/genes.json` -- reusable Gene definitions
+- `$EVOLVER_HOME/gep/capsules.json` -- success capsules
+- `$EVOLVER_HOME/gep/events.jsonl` -- append-only evolution events
 
 ---
 

package/assets/gep/genes.seed.json

@@ -491,6 +491,318 @@
         "execing or deserializing anything from the payload"
       ],
       "asset_id": "sha256:ac2a2f185390aef37996651ef21355f4beb437049e52a6ca3898619a8d648084"
+    },
+    {
+      "type": "Gene",
+      "category": "optimize",
+      "schema_version": "1.8.0",
+      "epigenetic_marks": [],
+      "learning_history": [],
+      "anti_patterns": [],
+      "routing_hint": {
+        "tier": "mid",
+        "reasoning_level": "medium"
+      },
+      "tool_policy": null,
+      "id": "gene_claude_prompt_budget_ledger",
+      "signals_match": [
+        "prompt_budget_measurement",
+        "token_budget_overflow",
+        "context_explosion",
+        "上下文爆了",
+        "token 超限",
+        "context budget"
+      ],
+      "preconditions": [
+        "A context-limit failure needs attribution before changing prompts, tools, memory, or handoff format",
+        "At least one local prompt/context source can be measured or estimated independently"
+      ],
+      "strategy": [
+        "Create a budget ledger before editing: fixed system/harness text, user/project instructions, memory index, recalled memories, tool schemas, MCP instructions, skill manuals, agent descriptions, and user-pasted payload",
+        "Rank sources by marginal savings and risk; prefer lazy-loading low-relevance tool/manual detail before compressing high-priority policy",
+        "Record both absolute tokens and percentage of the total so regressions can be caught when new tools or skills are added",
+        "Attach each compression to a verification target: selected tool still callable, selected skill still loadable, safety rule still present, or handoff still sufficient",
+        "After changes, re-run the same ledger measurement and report the before/after delta with any residual irreducible context cost"
+      ],
+      "validation": [
+        "node --test test/contextSchemaRoutingGene.test.js",
+        "node scripts/validate-modules.js ./src/gep/signals ./src/gep/contextRoutingGene"
+      ],
+      "constraints": {
+        "max_files": 8,
+        "forbidden_paths": [
+          ".git",
+          "node_modules"
+        ]
+      },
+      "summary": "Diagnose context explosions with a prompt-budget ledger before deciding whether to compress tools, skills, memory, policy, or pasted transcripts.",
+      "avoid": [
+        "guessing the largest source without measuring it",
+        "optimizing a small memory index while ignoring much larger always-on tool schemas",
+        "reporting a context fix without before/after numbers and a runtime verification target"
+      ],
+      "asset_id": "sha256:d5f2bffabeac6076ed455b057d0de57c197f2d257bff4ce1c4efa0ad7f16b48a"
+    },
+    {
+      "type": "Gene",
+      "category": "optimize",
+      "schema_version": "1.8.0",
+      "epigenetic_marks": [],
+      "learning_history": [],
+      "anti_patterns": [],
+      "routing_hint": {
+        "tier": "mid",
+        "reasoning_level": "medium"
+      },
+      "tool_policy": null,
+      "id": "gene_claude_context_schema_routing",
+      "signals_match": [
+        "claude_code_context_bloat",
+        "schema_routing_gene_request",
+        "蒸馏成基因",
+        "Claude Code context",
+        "Available agent types",
+        "MCP Server Instructions"
+      ],
+      "preconditions": [
+        "Claude Code or another harness injects large tool/MCP/skill instructions before the user task",
+        "The failure mode is prompt/context size or duplicated capability guidance, while runtime approval gates and parameter validation remain enforced"
+      ],
+      "strategy": [
+        "Classify the bloat source first: user/project policy, memory index, recalled memory bodies, tool schemas, MCP server instructions, skill descriptions, agent-type descriptions, or pasted transcript payloads",
+        "Route the task to the most specific compression Gene instead of applying one generic shortening pass; keep this Gene as a compliance-first dispatcher and decision record",
+        "Preserve complete delivery: retain user-preference, approval-gate, validation, and signature requirements while compressing their wording into stable policy references",
+        "Keep exact tool schemas available through the authorized runtime loader; routing Genes select a capability family and the runtime loader supplies authoritative parameters and validation",
+        "Validate the routed path by proving the selected Gene appears through selector or recall injection, the rendered hint stays under the injection ceiling, and an approved runtime loader can still provide the exact schema when needed"
+      ],
+      "validation": [
+        "node --test test/contextSchemaRoutingGene.test.js test/recallInject.test.js test/selector.test.js",
+        "node scripts/validate-modules.js ./src/gep/assetStore ./src/gep/recallInject ./src/gep/selector ./src/gep/signals ./src/gep/contextRoutingGene ./src/gep/schemas/gene",
+        "node scripts/validate-suite.js"
+      ],
+      "constraints": {
+        "max_files": 8,
+        "forbidden_paths": [
+          ".git",
+          "node_modules"
+        ]
+      },
+      "summary": "Dispatch Claude Code context-bloat work to specialized Genes while retaining approval gates and requiring exact schemas from authorized runtime loaders.",
+      "avoid": [
+        "using one broad summary when a narrower tool-schema, skill-manual, memory, or transcript compression Gene applies",
+        "summarizing away exact tool JSON schemas at the moment a real tool call needs runtime validation",
+        "removing user-preference, approval-gate, validation, or signature requirements merely to save tokens",
+        "treating lazy loading as a substitute for the runtime loader and its authoritative parameter contract"
+      ],
+      "asset_id": "sha256:6a74dc27cf91a6c3ac802851a974a7dd86d658bb34fa9b1647a7756a797e3161"
+    },
+    {
+      "type": "Gene",
+      "category": "optimize",
+      "schema_version": "1.8.0",
+      "epigenetic_marks": [],
+      "learning_history": [],
+      "anti_patterns": [],
+      "routing_hint": {
+        "tier": "mid",
+        "reasoning_level": "medium"
+      },
+      "tool_policy": null,
+      "id": "gene_claude_tool_schema_lazy_load",
+      "signals_match": [
+        "tool_schema_bloat",
+        "mcp_tool_schema",
+        "lazy_load_schema",
+        "工具 schema 太大",
+        "tool schema too large",
+        "MCP tool schema"
+      ],
+      "preconditions": [
+        "The fixed context includes full tool or MCP JSON schemas before the task has selected a tool family",
+        "The goal is to reduce always-on prompt load without weakening the exact schema available at call time"
+      ],
+      "strategy": [
+        "Replace always-on full schemas with a compact tool-family card: capability name, trigger words, risk class, and a pointer to the authoritative schema loader",
+        "Delay expansion of exact parameter schemas until the planner selects that tool family or the model is about to emit a tool call",
+        "Keep schema validation at the tool boundary, not in the compressed prompt; invalid parameters must still be rejected by the runtime schema",
+        "Measure before and after: count always-on schema bytes/tokens, selected schema bytes/tokens, and total prompt size for a representative task",
+        "Regression-test at least one real tool call per lazy-loaded family so the compression cannot pass by merely hiding unavailable tools"
+      ],
+      "validation": [
+        "node --test test/contextSchemaRoutingGene.test.js test/recallInject.test.js",
+        "node scripts/validate-modules.js ./src/gep/signals ./src/gep/recallInject ./src/gep/contextRoutingGene"
+      ],
+      "constraints": {
+        "max_files": 12,
+        "forbidden_paths": [
+          ".git",
+          "node_modules"
+        ]
+      },
+      "summary": "Shrink always-on tool/MCP schema context by routing through compact tool-family cards and loading exact JSON schemas just in time.",
+      "avoid": [
+        "replacing exact schemas with natural-language guesses at call time",
+        "dropping enum constraints, required fields, or permission prompts from the runtime boundary",
+        "claiming savings without a before/after token measurement and one real tool-call regression"
+      ],
+      "asset_id": "sha256:84fe72cb104f2806d68c0289663350252ee4ce5c1c752468eddc43ef95bbf326"
+    },
+    {
+      "type": "Gene",
+      "category": "optimize",
+      "schema_version": "1.8.0",
+      "epigenetic_marks": [],
+      "learning_history": [],
+      "anti_patterns": [],
+      "routing_hint": {
+        "tier": "mid",
+        "reasoning_level": "medium"
+      },
+      "tool_policy": null,
+      "id": "gene_claude_skill_manual_routing",
+      "signals_match": [
+        "skill_list_bloat",
+        "skill_manual_bloat",
+        "Available agent types",
+        "MCP Server Instructions",
+        "skill 列表太长",
+        "技能列表太长"
+      ],
+      "preconditions": [
+        "The prompt includes many skill descriptions, agent type descriptions, or MCP server instructions unrelated to the current task",
+        "The harness can load a skill or manual after a routing decision is made"
+      ],
+      "strategy": [
+        "Convert each long skill/manual into a short route card containing name, one-line capability, hard trigger, skip trigger, and safety class",
+        "Select at most the relevant skill/manual before loading its full instructions; do not inject every skill body on every turn",
+        "Keep slash-command and user-invocable skill names exact so the router never invents unavailable skills",
+        "Preserve mandatory global policy outside skill manuals when the policy applies across all tools, but move skill-local details behind the skill loader",
+        "Add tests that route a representative Lark/Pencil/Browser/Claude-API task to the right card while unrelated cards remain compressed"
+      ],
+      "validation": [
+        "node --test test/contextSchemaRoutingGene.test.js",
+        "node scripts/validate-modules.js ./src/gep/signals ./src/gep/contextRoutingGene"
+      ],
+      "constraints": {
+        "max_files": 12,
+        "forbidden_paths": [
+          ".git",
+          "node_modules"
+        ]
+      },
+      "summary": "Compress large skill, agent-type, and MCP instruction lists into route cards, loading full manuals only after the route is selected.",
+      "avoid": [
+        "embedding every skill manual because one task might need one of them",
+        "inventing skill names or aliases not present in the runtime registry",
+        "moving cross-cutting safety policy behind an optional skill loader"
+      ],
+      "asset_id": "sha256:5d698cd132f4a9b32cc2e042de6131d8d175766acda50e8455d12358f1a5760c"
+    },
+    {
+      "type": "Gene",
+      "category": "optimize",
+      "schema_version": "1.8.0",
+      "epigenetic_marks": [],
+      "learning_history": [],
+      "anti_patterns": [],
+      "routing_hint": {
+        "tier": "mid",
+        "reasoning_level": "medium"
+      },
+      "tool_policy": null,
+      "id": "gene_claude_transcript_handoff_compression",
+      "signals_match": [
+        "transcript_context_bloat",
+        "conversation_handoff_bloat",
+        "pasted_transcript_bloat",
+        "随便传一个会话上下文就爆了",
+        "会话上下文就爆了",
+        "full transcript too large"
+      ],
+      "preconditions": [
+        "A user or agent is transferring conversation context, logs, or transcript history into a new session",
+        "The receiving session needs task continuity, not every raw tool schema or every previous token"
+      ],
+      "strategy": [
+        "Extract a handoff packet with: objective, current branch/worktree, changed files, decisions made, commands already run, failing/passing evidence, blockers, and next irreversible action",
+        "Drop raw tool schemas, repeated system prompts, screenshots already summarized, and low-level logs unless they are direct evidence for a current failure",
+        "Keep clickable file paths and exact failing command output snippets; preserve unresolved errors verbatim enough to reproduce them",
+        "Separate durable project memory from ephemeral transcript detail; save durable facts to memory only when they are non-obvious and future-relevant",
+        "Verify the handoff by asking whether an isolated agent can continue from the packet without reading the original full transcript"
+      ],
+      "validation": [
+        "node --test test/contextSchemaRoutingGene.test.js",
+        "node scripts/validate-modules.js ./src/gep/signals ./src/gep/contextRoutingGene"
+      ],
+      "constraints": {
+        "max_files": 8,
+        "forbidden_paths": [
+          ".git",
+          "node_modules"
+        ]
+      },
+      "summary": "Turn bulky pasted transcripts into compact handoff packets that preserve decisions, evidence, files, validation, and next actions.",
+      "avoid": [
+        "copying full transcripts, system prompts, or tool schemas into the next session by default",
+        "dropping exact failing output or branch/worktree state needed to continue safely",
+        "saving ephemeral conversation detail as durable memory"
+      ],
+      "asset_id": "sha256:32903bb5e4813856091738d4bd99c1579843b5eccaa7661ab028ce010423cfcc"
+    },
+    {
+      "type": "Gene",
+      "category": "optimize",
+      "schema_version": "1.8.0",
+      "epigenetic_marks": [],
+      "learning_history": [],
+      "anti_patterns": [],
+      "routing_hint": {
+        "tier": "mid",
+        "reasoning_level": "medium"
+      },
+      "tool_policy": null,
+      "id": "gene_claude_memory_index_budget",
+      "signals_match": [
+        "memory_index_budget",
+        "memory_recall_budget",
+        "memory_index_bloat",
+        "memory_recall_bloat",
+        "memory index",
+        "memory recall",
+        "memory.md too large",
+        "memory 索引",
+        "memory 全量",
+        "MEMORY.md"
+      ],
+      "preconditions": [
+        "Memory index or recalled memory bodies are suspected of consuming too much context",
+        "The system has a retrieval path that can inject only top relevant memories instead of the full memory store"
+      ],
+      "strategy": [
+        "Measure the memory index separately from recalled memory bodies and from unrelated tool/MCP schema overhead",
+        "Keep the index as one-line hooks with links; move detailed facts into individual memory files retrieved by relevance",
+        "Set guardrails: index under roughly 5k tokens is usually acceptable, around 10k needs pruning, and full memory-body injection must be replaced by retrieval",
+        "When pruning, merge duplicate memories and delete stale wrong facts rather than deleting high-value durable constraints",
+        "Validate recall quality with representative prompts before and after pruning so context savings do not hide important project constraints"
+      ],
+      "validation": [
+        "node --test test/contextSchemaRoutingGene.test.js",
+        "node scripts/validate-modules.js ./src/gep/signals ./src/gep/contextRoutingGene"
+      ],
+      "constraints": {
+        "max_files": 8,
+        "forbidden_paths": [
+          ".git",
+          "node_modules"
+        ]
+      },
+      "summary": "Control memory context cost by keeping MEMORY.md as a lean index and relying on relevance-based recall for detailed memory bodies.",
+      "avoid": [
+        "blaming memory before measuring tool/MCP/skill schema overhead separately",
+        "injecting every memory body into every session",
+        "deleting durable user/project constraints just to make the index look smaller"
+      ],
+      "asset_id": "sha256:c85f323d8e5f982c5d551409a9f9782a235e3e23ad16d035329b0a7446dd1884"
     }
   ]
 }

package/cli-options.js

@@ -0,0 +1,73 @@
+'use strict';
+
+const path = require('path');
+
+const PROXY_PATH_FLAGS = new Map([
+  ['--home', 'home'],
+  ['--store', 'store'],
+  ['--settings', 'settings'],
+  ['--env-file', 'envFile'],
+]);
+
+function expandHomePath(value, env = process.env) {
+  if (value === '~') return env.HOME || require('os').homedir();
+  if (value.startsWith('~/') || value.startsWith('~\\')) {
+    return path.join(env.HOME || require('os').homedir(), value.slice(2));
+  }
+  return value;
+}
+
+function parseProxyCliPathOptions(argv, env = process.env) {
+  const options = {};
+  for (let index = 0; index < argv.length; index += 1) {
+    const arg = String(argv[index]);
+    const equalsIndex = arg.indexOf('=');
+    const flag = equalsIndex >= 0 ? arg.slice(0, equalsIndex) : arg;
+    const key = PROXY_PATH_FLAGS.get(flag);
+    if (!key) continue;
+
+    const value = equalsIndex >= 0 ? arg.slice(equalsIndex + 1) : argv[++index];
+    if (!value || !String(value).trim() || (equalsIndex < 0 && String(value).startsWith('-'))) {
+      throw new Error(flag + ' requires a path');
+    }
+    options[key] = path.resolve(expandHomePath(String(value).trim(), env));
+  }
+  return options;
+}
+
+function applyProxyCliPathOptions(options, env = process.env) {
+  if (options.envFile) env.EVOLVER_ENV_FILE = options.envFile;
+  if (options.home) {
+    env.EVOMAP_DIR = options.home;
+    env.EVOLVER_HOME = options.home;
+    env.EVOMAP_HOME = options.home;
+    env.EVOLVER_SETTINGS_DIR = options.home;
+    env.EVOLVER_PROXY_STORE = path.join(options.home, 'mailbox');
+    env.EVOLVER_PROXY_SETTINGS_FILE = path.join(options.home, 'settings.json');
+    env.EVOMAP_PROXY_TRACE_FILE = path.join(options.home, 'proxy', 'traces', 'proxy-traces.jsonl');
+  }
+  if (options.store) env.EVOLVER_PROXY_STORE = options.store;
+  if (options.settings) env.EVOLVER_PROXY_SETTINGS_FILE = options.settings;
+  return options;
+}
+
+function prepareProxyCliEnvironment(argv, env = process.env, dotenv = require('dotenv')) {
+  const options = parseProxyCliPathOptions(argv, env);
+  let envFile = { loaded: false, error: null };
+  const selectedEnvFile = options.envFile || env.EVOLVER_ENV_FILE;
+  if (selectedEnvFile) {
+    const resolvedEnvFile = path.resolve(expandHomePath(String(selectedEnvFile).trim(), env));
+    env.EVOLVER_ENV_FILE = resolvedEnvFile;
+    const result = dotenv.config({ path: resolvedEnvFile, processEnv: env });
+    envFile = { loaded: !result.error, error: result.error || null };
+  }
+  applyProxyCliPathOptions(options, env);
+  return { options, envFile };
+}
+
+module.exports = {
+  applyProxyCliPathOptions,
+  expandHomePath,
+  parseProxyCliPathOptions,
+  prepareProxyCliEnvironment,
+};

package/index.js

@@ -206,6 +206,19 @@ if (process.argv[2] === 'proxy-token') {
   }
 }
 
+const {
+  applyProxyCliPathOptions,
+  prepareProxyCliEnvironment,
+} = require('./cli-options');
+
+let _proxyCliBootstrap = { options: {}, envFile: { loaded: false, error: null } };
+let _proxyCliBootstrapError = null;
+try {
+  _proxyCliBootstrap = prepareProxyCliEnvironment(process.argv.slice(2), process.env);
+} catch (error) {
+  _proxyCliBootstrapError = error;
+}
+
 // Load .env BEFORE any internal require so that a2aProtocol and ATP
 // modules see A2A_NODE_SECRET / A2A_NODE_ID / A2A_HUB_URL at first
 // access and never fall back to a stale persisted/cached secret.
@@ -242,6 +255,9 @@ try {
   if (_root && _root !== process.cwd()) {
     require('dotenv').config({ path: _path.join(_root, '.env') });
   }
+  // CLI paths have the highest priority, including over values loaded from
+  // either the selected env file or the repository defaults.
+  applyProxyCliPathOptions(_proxyCliBootstrap.options, process.env);
   if (_prevQuiet === undefined) delete process.env.EVOLVER_QUIET_PARENT_GIT;
   else process.env.EVOLVER_QUIET_PARENT_GIT = _prevQuiet;
 } catch (e) { /* dotenv is optional */ }
@@ -831,6 +847,14 @@ function refuseHelloIfDaemonRunning(toolLabel) {
 }
 
 async function main() {
+  if (_proxyCliBootstrapError) {
+    console.error('[evolver] ' + _proxyCliBootstrapError.message);
+    process.exitCode = 1;
+    return;
+  }
+  if (_proxyCliBootstrap.envFile.error) {
+    console.warn('[evolver] Failed to load --env-file: ' + _proxyCliBootstrap.envFile.error.message);
+  }
   const args = process.argv.slice(2);
   const command = args[0];
   // Solo mode (--solo): the "constrained wild" profile. Implies loop (a solo
@@ -1450,6 +1474,7 @@ async function main() {
             const { startProxy } = require('./src/proxy');
             const proxyInfo = await startProxy({
               hubUrl: process.env.A2A_HUB_URL,
+              dataDir: process.env.EVOLVER_PROXY_STORE,
               clientSettings: {},
             });
             console.log('[Proxy] Started on ' + proxyInfo.url);
@@ -3690,6 +3715,11 @@ async function main() {
                                 (read versioned node secrets from a JSON file)
     - --hub-private-key=<path>|--hub-private-key <path>
                                 (decrypt hub_key_envelope trace rows with a local private key)
+  - run path flags (CLI overrides environment variables):
+    - --home=<dir>              (root for assets, mailbox, settings, and traces)
+    - --store=<dir>             (mailbox store directory; EVOLVER_PROXY_STORE)
+    - --settings=<path>         (proxy settings file; EVOLVER_PROXY_SETTINGS_FILE)
+    - --env-file=<path>         (environment file; EVOLVER_ENV_FILE)
   - webui flags:
     - --port=<N>               (local Web UI port, default 19821)
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@evomap/evolver",
-  "version": "1.92.0",
+  "version": "1.94.0",
   "description": "A GEP-powered self-evolution engine for AI agents. Features automated log analysis and Genome Evolution Protocol (GEP) for auditable, reusable evolution assets.",
   "main": "index.js",
   "bin": {
@@ -57,6 +57,7 @@
   },
   "files": [
     "assets/",
+    "cli-options.js",
     "index.js",
     "src/",
     "scripts/",