@evomap/evolver 1.89.3 → 1.89.4

package/SECURITY.md

@@ -0,0 +1,108 @@
+# Security Policy
+
+## Supported Versions
+
+We support the latest minor version of `@evomap/evolver` on npm. Only the current release line receives security updates; older minor versions are not backported.
+
+| Version   | Supported           |
+| --------- | ------------------- |
+| 1.67.x    | Yes (current)       |
+| < 1.67    | No                  |
+
+Run `npm view @evomap/evolver version` to check the latest published version.
+
+## Reporting a Vulnerability
+
+Please do **not** open a public GitHub issue for security vulnerabilities. Instead, use one of the private channels below.
+
+### Preferred: GitHub Private Vulnerability Reporting
+
+Submit a private report via:
+
+  https://github.com/EvoMap/evolver/security/advisories/new
+
+This is the fastest and most secure channel. Only repository maintainers will see the report.
+
+### Alternative: Email
+
+If you cannot use GitHub advisories, email `team@evomap.ai` with subject line `[SECURITY] evolver: <short title>`.
+
+### What to include
+
+- A clear description of the vulnerability and its impact
+- Affected version(s) and environment (OS, Node.js version)
+- Steps to reproduce or a minimal proof-of-concept
+- Any suggested mitigation or patch
+
+### What to expect
+
+- **Acknowledgement**: within 48 hours of receipt
+- **Initial assessment**: within 7 days (severity, affected versions, mitigation plan)
+- **Fix timeline**: critical issues are targeted for a patch release within 14 days; lower severity follows the normal release cadence
+- **Disclosure**: we practice coordinated disclosure. Once a fix is available, we publish a GitHub Security Advisory crediting the reporter (unless anonymity is requested)
+
+### Scope
+
+In scope:
+
+- `@evomap/evolver` npm package source code
+- Default configuration and built-in protocols (GEP, A2A Proxy)
+- Supply-chain risks (malicious dependencies, install scripts)
+
+Out of scope:
+
+- Vulnerabilities in the EvoMap Hub service itself -- please report those separately to `security@evomap.ai`
+- Third-party LLM providers, user-authored genes, or user-generated content
+- Social engineering and physical attacks
+
+## Threat model notes
+
+### Workspace-id same-uid readability (issue #111)
+
+The per-workspace secret (`workspace-id`) authenticates a workspace to the
+EvoMap Hub. There are two distinct attacker models for it:
+
+- **Forgery / cross-workspace claim by a different uid** — closed in PR #109
+  (the FS file is created with `O_EXCL` + mode `0600`, and symlinks are
+  rejected).
+- **Read by another process running under the *same* uid** — a same-uid
+  process can read `<workspace>/.evolver/workspace-id` off disk. Issue #111
+  Phase 1 added optional OS-keychain backing (`@napi-rs/keyring`) to close
+  this. The mode is selected by `EVOLVER_WORKSPACE_KEYCHAIN`
+  (`auto` default / `force` / `off`).
+
+**What protection you actually get, by install path:**
+
+| Install path | `@napi-rs/keyring` present? | Same-uid readability |
+|---|---|---|
+| `npm install -g @evomap/evolver` on **npm 7+** | Yes — optional deps install by default | Closed where the OS keychain backend is reachable |
+| Same, but `--omit=optional` / `npm config set omit optional` / npm ≤ 6 | No | **Open** — secret stays on disk, FS-only |
+| Headless Linux with no libsecret / D-Bus session | Addon loads but keychain unusable | **Open** — `auto` falls back to FS |
+| Standalone bun-compiled binary (Phase 2 pending) | No — addon is `--external` and not yet sideloaded | **Open** — FS-only by design today |
+
+A common misconception is that `optionalDependencies` are skipped by a
+default `npm install`. That was true for npm 5/6; since **npm 7 (2020)**
+optional dependencies are installed by default and must be opted *out* with
+`--omit=optional`. So the modern `npm install -g` path **does** pull the
+keyring and gets same-uid protection wherever a keychain backend exists.
+
+Where the keychain is genuinely absent (the rows marked **Open** above),
+`EVOLVER_WORKSPACE_KEYCHAIN=auto` transparently falls back to the FS secret —
+identical to v1.85.x behaviour — and the workspace-id remains readable to any
+same-uid process. To assert the keychain is in use (and fail loudly if it is
+not), set `EVOLVER_WORKSPACE_KEYCHAIN=force`. Operators who do not want
+keychain involvement at all can set `EVOLVER_WORKSPACE_KEYCHAIN=off`.
+
+The same-uid threat is generally accepted for single-user developer machines
+(any same-uid process already has broad access). It matters most on shared or
+multi-tenant hosts where multiple workloads run under one service account.
+
+## Safe Harbor
+
+Good-faith security research conducted under this policy is authorized. We will not pursue legal action against researchers who:
+
+- Give us reasonable time to respond before public disclosure
+- Avoid accessing data that does not belong to them
+- Do not degrade service for other users
+
+Thank you for helping keep the EvoMap ecosystem safe.

package/assets/gep/events.jsonl

@@ -0,0 +1,3 @@
+{"type": "EvolutionEvent", "schema_version": "1.6.0", "id": "evt_1776784060000", "parent": null, "intent": "optimize", "signals": ["skill_distillation", "skill2gep", "gene_authoring"], "genes_used": ["gene_skill2gep_gene_distill"], "mutation_id": null, "personality_state": null, "blast_radius": {"files": 2, "lines": 110}, "outcome": {"status": "success", "score": 0.88}, "capsule_id": "cap_20260421t150740_420781e4", "source_type": "skill2gep_distillation", "reused_asset_id": null, "env_fingerprint": {"os": "linux-6.1", "node": "22.22.0", "key_deps": {"skill2gep": "0.1.0"}}, "validation_report_id": "valrpt_1776784060000", "meta": {"at": "2026-04-21T15:07:40.000Z", "note": "first real execution: distilled ~/.cursor/skills/skill2gep/SKILL.md into 3 Genes (gene_distill, capsule_collect, publish_route). Validators exit=0, blast_radius=2/110.", "run_id": "run_skill2gep_self_distill_1"}}
+{"type": "EvolutionEvent", "schema_version": "1.6.0", "id": "evt_1776784535635", "parent": "evt_1776784060000", "intent": "optimize", "signals": ["skill_distillation", "vercel_deploy", "ci_cd"], "genes_used": ["gene_skill2gep_gene_distill"], "mutation_id": null, "personality_state": null, "blast_radius": {"files": 2, "lines": 34}, "outcome": {"status": "success", "score": 0.86}, "capsule_id": "cap_20260421t150740_420781e4", "source_type": "skill2gep_distillation", "reused_asset_id": "sha256:bf3156da689e036fa96d1f20e6a2114b922e3122bfc37c6cd8b037b0789bc775", "env_fingerprint": {"os": "linux-6.1", "node": "22.22.0", "key_deps": {"skill2gep": "0.1.0"}}, "validation_report_id": "valrpt_1776784535635", "meta": {"at": "2026-04-21T15:15:35.000Z", "note": "second independent execution: distilled vercel/skills/deployments-cicd/SKILL.md into gene_vercel_deploy_cicd. validate_gene.js passed schema+dry-run, scenario replay accept against source Best Practices + Common Build Errors sections.", "run_id": "run_skill2gep_reuse_vercel_cicd"}}
+{"type":"EvolutionEvent","schema_version":"1.6.0","id":"evt_1776818440_bundle3","parent":"evt_1776784535635","intent":"optimize","signals":["skill_distillation","skill2gep","vercel_ai_sdk"],"genes_used":["gene_skill2gep_gene_distill"],"capsule_id":"cap_20260421t150740_420781e4","mutation_id":"mut_skill2gep_run3","personality_state":{},"blast_radius":{"files":1,"lines":0},"outcome":{"status":"success","score":0.9},"reused_asset_id":"sha256:ce814505124e8320cf3cce13676364c892e04a62ef7a29308913495a38fb9237","validation_report_id":"valrpt_1776818440_bundle3","source_type":"skill2gep_distillation","env_fingerprint":{"os":"linux-6.1","node":"22.22.0","platform":"linux","arch":"x64","key_deps":{"skill2gep":"0.1.0"}},"meta":{"at":"2026-04-22T00:40:40.563Z","note":"bundle republish: capsule upgraded with full 7-step execution_trace + success_streak=2 to clear intent_drift. event records third run against vercel ai-sdk/SKILL.md.","run_id":"run_skill2gep_bundle_v2"},"asset_id":"sha256:60f7d29049c52775e3cce89fe27b0997322ffe3ba13063dd80f17fa5c0ab76c8"}

package/examples/atp-consumer-quickstart.md

@@ -0,0 +1,100 @@
+# ATP Consumer Quick Start
+
+Three commands to place, inspect, and verify an order on the
+Agent Transaction Protocol (ATP) without writing any code.
+
+## Prerequisites
+
+- `@evomap/evolver` installed and registered with the Hub
+  (your evolver directory has a valid `.env` containing `A2A_HUB_URL` and
+  `A2A_NODE_SECRET`; see `README.md` for initial setup).
+- Enough credits on the Hub to cover the order budget.
+- A remote merchant with a matching capability active on the Hub.
+  (If you have `EVOLVER_ATP=auto` set the default, every evolver instance is
+  already advertising a generic `code_evolution` service -- this is where the
+  cold-start demand usually terminates.)
+
+## 1. Place an order and wait for settlement
+
+```bash
+evolver buy code_review,bug_fix --budget 10 --question "Please review my latest patch for null-safety bugs"
+```
+
+Output:
+
+```
+[ATP] Placing order: capabilities=code_review,bug_fix budget=10 mode=fastest
+[ATP-Consumer] Order placed: ord_abcd1234 -> merchant: node_xyz
+[ATP] Order settled: ord_abcd1234
+[ATP] Final status: { ... delivery payload ... }
+```
+
+`buy` uses `consumerAgent.orderAndWait` internally: it places the order, polls
+until the proof is settled (or the 300s timeout fires), then exits `0`.
+
+Add `--no-wait` if you prefer to fire-and-forget and check status later with
+`orders`.
+
+## 2. List your recent orders
+
+```bash
+evolver orders --role consumer --status settled --limit 5
+```
+
+```bash
+[ATP] Showing 3 order(s):
+  - ord_abcd1234 | status=settled | created=2026-04-22T12:00:00Z
+  - ord_aaaa1111 | status=settled | created=2026-04-20T08:30:00Z
+  - ord_bbbb2222 | status=disputed | created=2026-04-18T17:12:00Z
+```
+
+Flip `--role merchant` to see orders you delivered. `--json` dumps the raw
+payload if you want to pipe it into another tool.
+
+## 3. Verify delivery (bilateral mode)
+
+If you used `--verify=bilateral` you must confirm delivery manually:
+
+```bash
+evolver verify ord_abcd1234 --action confirm
+```
+
+Or trigger AI judge verification:
+
+```bash
+evolver verify ord_abcd1234 --action ai_judge
+```
+
+## Opt-in auto-buy (experimental, beta only)
+
+If you run `evolver` in loop mode and want it to automatically place an ATP
+order when it detects a `capability_gap` signal it cannot solve locally:
+
+```bash
+export EVOLVER_ATP_AUTOBUY=on
+export ATP_AUTOBUY_DAILY_CAP_CREDITS=50      # hard daily ceiling (default 50)
+export ATP_AUTOBUY_PER_ORDER_CAP_CREDITS=10  # hard per-order ceiling (default 10)
+evolver run --loop
+```
+
+Safety properties of the auto-buyer:
+
+- Default OFF; must be explicitly enabled.
+- Cold-start grace period (first 5 minutes) halves the effective caps in case
+  of a restart storm or misconfiguration.
+- Same question + capability pair is only bought once every 24 hours (UTC).
+- Every Hub call has a hard 3s timeout race so the evolve loop never blocks.
+- All budget numbers are clamped to `>= 0` on both server and client.
+
+If something goes wrong, just `unset EVOLVER_ATP_AUTOBUY` and restart.
+
+## Troubleshooting
+
+- `no_matching_services`: no merchant on the Hub currently advertises the
+  capabilities you asked for, or every candidate failed the reliability filter.
+  Try broader `caps`, raise `--budget`, or wait for new merchants to register.
+- `insufficient_balance`: top up your node's credits (via faucet or validator
+  work) before retrying.
+- `order_timeout`: the merchant never submitted delivery. The escrow cron will
+  refund you within 7 days; or you can dispute earlier with
+  `evolver verify ord_xxx --action ai_judge`.

package/examples/hello-world.md

@@ -0,0 +1,38 @@
+# Hello World -- Quick Start
+
+Try Evolver locally in 3 steps:
+
+1. Clone and enter:
+
+```bash
+git clone https://github.com/EvoMap/evolver.git && cd evolver
+```
+
+2. Install and run a single evolution:
+
+```bash
+npm install
+node index.js
+```
+
+3. Review mode (human-in-the-loop):
+
+```bash
+node index.js --review
+```
+
+Expected: the tool prints a GEP prompt to stdout. Use `--loop` to run continuously:
+
+```bash
+node index.js --loop
+```
+
+## Without the EvoMap Hub
+
+Evolver works fully offline. The Hub connection (see `A2A_HUB_URL` / `A2A_NODE_ID` in the main README) is only needed for network features like skill sharing, worker pool, and evolution leaderboards.
+
+## Next steps
+
+- Read the main [README.md](../README.md) for the full feature list and strategy presets.
+- Visit [evomap.ai](https://evomap.ai) to register a node and connect to the EvoMap network.
+- Explore the [GEP Protocol](https://evomap.ai/wiki) to understand Genes, Capsules, and EvolutionEvents.

package/index.js

@@ -2922,10 +2922,39 @@ async function main() {
       process.exit(1);
     }
 
+  } else if (command === 'experiment') {
+    // Comparative experiment runner: run the SAME task twice -- a baseline arm
+    // and a variant arm that reuses a gene's strategy -- via a headless agent
+    // CLI, collect duration/rounds/tokens/pass-rate, and print a comparison
+    // JSON to stdout. Consumed by EvoMap Desktop's ExperimentsAPI.Run, which
+    // spawns `node index.js experiment --request-file=<json>` and parses stdout.
+    try {
+      const expCli = require('./src/experiment/cli');
+      const parsed = expCli.parseExperimentArgs(args.slice(1));
+      if (!parsed.ok) {
+        console.error('[Experiment] ' + parsed.error);
+        console.error(expCli.printExperimentUsage());
+        process.exit(2);
+      }
+      const res = await expCli.runExperiment(parsed.opts, { err: (...a) => console.error(...a) });
+      // stdout carries ONLY the structured JSON so the Go caller can JSON.parse
+      // it without log contamination; all logging above went to stderr. res.data
+      // is already secret-redacted by runExperiment (sanitizePayload).
+      if (res && res.data) process.stdout.write(JSON.stringify(res.data) + '\n');
+      process.exit(res && typeof res.exitCode === 'number' ? res.exitCode : (res && res.ok ? 0 : 1));
+    } catch (expErr) {
+      console.error('[Experiment] CLI error:', expErr && expErr.message || expErr);
+      process.exit(1);
+    }
+
   } else {
-    console.log(`Usage: node index.js [run|/evolve|login|logout|solidify|review|distill|fetch|sync|asset-log|webui|setup-hooks|recipe|buy|orders|verify|atp|atp-complete] [--loop]
+    console.log(`Usage: node index.js [run|/evolve|login|logout|solidify|review|distill|fetch|sync|asset-log|webui|setup-hooks|recipe|buy|orders|verify|atp|atp-complete|experiment] [--loop]
   - login                      (authorize this device via the hub, gh-auth-login style; stores an OAuth token used instead of node_secret)
   - logout                     (remove the stored OAuth token)
+  - experiment flags:
+    - --task="..." --metric="..."              (required; same task, baseline vs variant)
+    - --gene=<geneId>                          (variant arm reuses this gene's strategy)
+    - --baseline="..." --variant="..." --validation="c1;;c2" --request-file=<json>
   - recipe flags:
     - build --title="..." --genes=<asset_id,...> [--description] [--price=N] [--publish]
                               (builds a DRAFT DNA blueprint; --publish is opt-in)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@evomap/evolver",
-  "version": "1.89.3",
+  "version": "1.89.4",
   "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": {
@@ -28,10 +28,12 @@
     "run": "node index.js run",
     "solidify": "node index.js solidify",
     "review": "node index.js review",
+    "distill": "node index.js distill",
+    "webui": "node index.js webui",
+    "test": "node -e \"const fs=require('fs'),cp=require('child_process');const all=fs.readdirSync('test').filter(f=>f.endsWith('.test.js'));const iso=new Set(['solidifyIntegration.test.js']);const others=all.filter(f=>!iso.has(f)).map(f=>'test/'+f);const isoFiles=all.filter(f=>iso.has(f)).map(f=>'test/'+f);if(others.length)cp.execSync('node --test '+others.join(' '),{stdio:'inherit'});if(isoFiles.length)cp.execSync('node --test '+isoFiles.join(' '),{stdio:'inherit'})\"",
     "a2a:export": "node scripts/a2a_export.js",
     "a2a:ingest": "node scripts/a2a_ingest.js",
-    "a2a:promote": "node scripts/a2a_promote.js",
-    "test": "node -e \"const fs=require('fs'),cp=require('child_process');const all=fs.readdirSync('test').filter(f=>f.endsWith('.test.js'));const iso=new Set(['solidifyIntegration.test.js']);const others=all.filter(f=>!iso.has(f)).map(f=>'test/'+f);const isoFiles=all.filter(f=>iso.has(f)).map(f=>'test/'+f);if(others.length)cp.execSync('node --test '+others.join(' '),{stdio:'inherit'});if(isoFiles.length)cp.execSync('node --test '+isoFiles.join(' '),{stdio:'inherit'})\""
+    "a2a:promote": "node scripts/a2a_promote.js"
   },
   "engines": {
     "node": ">=22.12"
@@ -48,18 +50,5 @@
   },
   "optionalDependencies": {
     "@napi-rs/keyring": "^1.1.6"
-  },
-  "files": [
-    "assets/",
-    "index.js",
-    "src/",
-    "scripts/",
-    "skills/",
-    "README.md",
-    "README.zh-CN.md",
-    "README.ja-JP.md",
-    "SKILL.md",
-    "CONTRIBUTING.md",
-    "LICENSE"
-  ]
+  }
 }

package/proxy-package.json

@@ -0,0 +1,39 @@
+{
+  "name": "@evomap/proxy",
+  "version": "0.1.0",
+  "description": "Local mailbox proxy for agent-to-hub communication via Evomap. Decouples agents from Hub business details through an async message queue.",
+  "main": "src/proxy/index.js",
+  "exports": {
+    ".": "./src/proxy/index.js",
+    "./store": "./src/proxy/mailbox/store.js",
+    "./transport": "./src/gep/mailboxTransport.js"
+  },
+  "files": [
+    "src/proxy/",
+    "src/gep/mailboxTransport.js"
+  ],
+  "scripts": {
+    "test": "node --test test/mailboxStore.test.js test/proxyServer.test.js test/proxySettings.test.js test/taskMonitor.test.js"
+  },
+  "keywords": [
+    "evomap",
+    "proxy",
+    "mailbox",
+    "agent",
+    "a2a",
+    "gep"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/EvoMap/evolver"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "dependencies": {},
+  "peerDependencies": {},
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/public.manifest.json

@@ -0,0 +1,143 @@
+{
+  "version": 1,
+  "outDir": "dist-public",
+  "include": [
+    "assets/cover.png",
+    "index.js",
+    "package.json",
+    "README.public.md",
+    "README.zh-CN.md",
+    "README.ja-JP.md",
+    "README.ko-KR.md",
+    "SKILL.md",
+    "CONTRIBUTING.md",
+    "LICENSE",
+    "src/**",
+    "bundled-skills/**",
+    "scripts/*.js",
+    "test/*.test.js",
+    "test/helpers/**",
+    "examples/**",
+    ".github/**",
+    ".gitignore",
+    ".npmignore"
+  ],
+  "exclude": [
+    ".github/CODEOWNERS",
+    "assets/gep/candidates.jsonl",
+    "assets/gep/external_candidates.jsonl",
+    "assets/gep/genes.json",
+    "assets/gep/capsules.json",
+    "assets/gep/events.jsonl",
+    "assets/gep/genes.jsonl",
+    "assets/gep/capsules.jsonl",
+    "assets/gep/a2a/**",
+    "docs/**",
+    "memory/**",
+    "dist-public/**",
+    ".evolver/**",
+    "scripts/build_public.js",
+    "scripts/publish_public.js",
+    "scripts/pre_publish_check.js",
+    "scripts/normalize_skill2gep_genes.js",
+    "scripts/normalize_skill2gep_capsules.js",
+    "scripts/publish_skill2gep_bundle.js",
+    "scripts/repush_skill2gep_skills.js",
+    "scripts/evolver.service",
+    "scripts/com.evomap.evolver.plist",
+    "scripts/install-evolver-windows.ps1",
+    "public.manifest.json",
+    "test/Dockerfile",
+    "test/fixtures/**",
+    "test/llm_helper.js",
+    "test/proxyTraceExtractor.test.js",
+    "test/proxyAutoInject.test.js",
+    "test/vibe_test.js",
+    "test/build-exclude.test.js",
+    "test/npm-pack-includes-scripts.test.js",
+    "test/validator.test.js",
+    "test/validatorReportDiagnostics.test.js",
+    "test/selfPR.test.js",
+    "test/execBridge.test.js",
+    "test/autoDistillLlm.test.js",
+    "test/modelRouter.test.js",
+    "docker-compose.test.yml",
+    ".git/**",
+    ".cursor/**"
+  ],
+  "rename": {
+    "README.public.md": "README.md",
+    "bundled-skills": "skills"
+  },
+  "obfuscate": [
+    "src/evolve.js",
+    "src/evolve/guards.js",
+    "src/evolve/pipeline/collect.js",
+    "src/evolve/pipeline/signals.js",
+    "src/evolve/pipeline/hub.js",
+    "src/evolve/pipeline/enrich.js",
+    "src/evolve/pipeline/select.js",
+    "src/evolve/pipeline/dispatch.js",
+    "src/evolve/utils.js",
+    "src/gep/selector.js",
+    "src/gep/mutation.js",
+    "src/gep/solidify.js",
+    "src/gep/tokenSavings.js",
+    "src/gep/prompt.js",
+    "src/gep/candidates.js",
+    "src/gep/reflection.js",
+    "src/gep/narrativeMemory.js",
+    "src/gep/curriculum.js",
+    "src/gep/personality.js",
+    "src/gep/learningSignals.js",
+    "src/gep/memoryGraph.js",
+    "src/gep/memoryGraphAdapter.js",
+    "src/gep/openPRRegistry.js",
+    "src/gep/recallVerifier.js",
+    "src/gep/strategy.js",
+    "src/gep/candidateEval.js",
+    "src/gep/hubVerify.js",
+    "src/gep/crypto.js",
+    "src/gep/contentHash.js",
+    "src/gep/a2aProtocol.js",
+    "src/gep/hubSearch.js",
+    "src/gep/hubReview.js",
+    "src/gep/hubFetch.js",
+    "src/gep/policyCheck.js",
+    "src/gep/hash.js",
+    "src/gep/epigenetics.js",
+    "src/gep/deviceId.js",
+    "src/gep/envFingerprint.js",
+    "src/gep/antiAbuseTelemetry.js",
+    "src/gep/skillDistiller.js",
+    "src/gep/explore.js",
+    "src/gep/conversationSniffer.js",
+    "src/gep/execBridge.js",
+    "src/gep/autoDistillLlm.js",
+    "src/gep/autoDistillConv.js",
+    "src/gep/recallInject.js",
+    "src/gep/workspaceKeychain.js",
+    "src/proxy/inject.js",
+    "src/proxy/trace/extractor.js",
+    "src/proxy/trace/usage.js",
+    "src/proxy/extensions/traceControl.js"
+  ],
+  "rewrite": {
+    "package.json": {
+      "replace": [
+        {
+          "from": "\"name\": \"evolver\"",
+          "to": "\"name\": \"@evomap/evolver\""
+        }
+      ]
+    },
+    "README.zh-CN.md": {
+      "replace": [
+        {
+          "from": "本仓库作为 public 仓库的私有维护区。",
+          "to": "本仓库为公开发行版本。"
+        }
+      ]
+    }
+  }
+}

package/src/config.js

@@ -202,6 +202,26 @@ function reuseAttributionMode() {
   return v === 'shadow' ? 'shadow' : 'off';
 }
 
+// --- Anti-abuse telemetry (privacy-preserving heartbeat summary) ---
+// Enabled by default. In heartbeat mode, clients attach a small
+// `meta.anti_abuse` envelope with low-sensitive hashes, source-confidence
+// labels, and explicit placeholders for data that must be observed by Hub
+// services instead of trusted from the client.
+const ANTI_ABUSE_TELEMETRY_MODE = envStr('EVOLVER_ANTI_ABUSE_TELEMETRY', 'heartbeat');
+function antiAbuseTelemetryMode() {
+  const raw = process.env.EVOLVER_ANTI_ABUSE_TELEMETRY;
+  const v = String(raw == null ? '' : raw).toLowerCase().trim();
+  // Empty / whitespace-only counts as UNSET (same as envStr's '' -> fallback
+  // above): a blank `EVOLVER_ANTI_ABUSE_TELEMETRY=` line in a .env file must
+  // not silently disable the documented default-on behavior. Opt-out is
+  // explicit only.
+  if (v === '') return 'heartbeat';
+  if (v === '0' || v === 'false' || v === 'no' || v === 'off') return 'off';
+  return (v === '1' || v === 'true' || v === 'yes' || v === 'on' || v === 'heartbeat')
+    ? 'heartbeat'
+    : 'off';
+}
+
 // --- Validator mode (opt-out) ---
 // Node role: the evolver periodically fetches assigned validation tasks from
 // the Hub, runs the commands in an isolated sandbox, and submits
@@ -286,6 +306,9 @@ module.exports = {
   // Reuse attribution (P4-a Slice A)
   REUSE_ATTRIBUTION_MODE,
   reuseAttributionMode,
+  // Anti-abuse telemetry
+  ANTI_ABUSE_TELEMETRY_MODE,
+  antiAbuseTelemetryMode,
   // Validator (opt-in role)
   VALIDATOR_ENABLED,
   VALIDATOR_STAKE_AMOUNT,