@evomap/evolver 1.87.1 → 1.87.2

package/assets/gep/candidates.jsonl

@@ -0,0 +1 @@
+{"type":"CapabilityCandidate","id":"cand_b9a66a5c","title":"Harden session log detection and fallback behavior","source":"signals","created_at":"2026-05-27T12:51:59.052Z","signals":["memory_missing","user_missing","session_logs_missing"],"tags":["memory_missing","user_missing","session_logs_missing","area:memory"],"shape":{"title":"Harden session log detection and fallback behavior","input":"Recent session transcript + memory snippets + user instructions","output":"A safe, auditable evolution patch guided by GEP assets","invariants":"Protocol order, small reversible patches, validation, append-only events","params":"Signals: memory_missing, user_missing, session_logs_missing","failure_points":"Missing signals, over-broad changes, skipped validation, missing knowledge solidification","evidence":"Signal present: session_logs_missing"}}

package/assets/gep/capsules.json

@@ -0,0 +1,4 @@
+{
+  "version": 1,
+  "capsules": []
+}

package/assets/gep/failed_capsules.json

@@ -0,0 +1,4 @@
+{
+  "version": 1,
+  "failed_capsules": []
+}

package/assets/gep/genes.json

@@ -0,0 +1,245 @@
+{
+  "version": 2,
+  "genes": [
+    {
+      "type": "Gene",
+      "id": "gene_gep_repair_from_errors",
+      "category": "repair",
+      "signals_match": [
+        "error|错误|异常|エラー|오류",
+        "exception|异常|例外|예외",
+        "failed|失败|失敗|실패|fail",
+        "unstable|不稳定|不安定|불안정",
+        "log_error",
+        "test_failure"
+      ],
+      "preconditions": [
+        "signals contains error-related indicators"
+      ],
+      "strategy": [
+        "Extract structured signals from logs and user instructions",
+        "Select an existing Gene by signals match (no improvisation)",
+        "Estimate blast radius (files, lines) before editing",
+        "Apply smallest reversible patch",
+        "Validate using declared validation steps; rollback on failure",
+        "Solidify knowledge: append EvolutionEvent, update Gene/Capsule store"
+      ],
+      "constraints": {
+        "max_files": 20,
+        "forbidden_paths": [
+          ".git",
+          "node_modules"
+        ]
+      },
+      "validation": [
+        "node scripts/validate-modules.js ./src/evolve ./src/gep/solidify ./src/gep/policyCheck ./src/gep/selector ./src/gep/memoryGraph ./src/gep/assetStore",
+        "node scripts/validate-suite.js"
+      ]
+    },
+    {
+      "type": "Gene",
+      "id": "gene_gep_optimize_prompt_and_assets",
+      "category": "optimize",
+      "signals_match": [
+        "protocol|协议|プロトコル|프로토콜",
+        "gep",
+        "prompt|提示词|提示|プロンプト|프롬프트",
+        "audit|审计|監査|감사",
+        "reusable|可复用|再利用|재사용"
+      ],
+      "preconditions": [
+        "need stricter, auditable evolution protocol outputs"
+      ],
+      "strategy": [
+        "Extract signals and determine selection rationale via Selector JSON",
+        "Prefer reusing existing Gene/Capsule; only create if no match exists",
+        "Refactor prompt assembly to embed assets (genes, capsules, parent event)",
+        "Reduce noise and ambiguity; enforce strict output schema",
+        "Validate by running node index.js run and ensuring no runtime errors",
+        "Solidify: record EvolutionEvent, update Gene definitions, create Capsule on success"
+      ],
+      "constraints": {
+        "max_files": 20,
+        "forbidden_paths": [
+          ".git",
+          "node_modules"
+        ]
+      },
+      "validation": [
+        "node scripts/validate-modules.js ./src/evolve ./src/gep/prompt ./src/gep/contentHash ./src/gep/skillDistiller",
+        "node scripts/validate-suite.js"
+      ]
+    },
+    {
+      "type": "Gene",
+      "id": "gene_gep_innovate_from_opportunity",
+      "category": "innovate",
+      "signals_match": [
+        "user_feature_request|功能请求|機能リクエスト|기능요청",
+        "user_improvement_suggestion|改进建议|改善提案|개선제안",
+        "perf_bottleneck|性能瓶颈|パフォーマンス|성능병목",
+        "capability_gap|能力缺口|機能ギャップ|역량공백",
+        "stable_success_plateau",
+        "external_opportunity|外部机会|外部機会|외부기회",
+        "bounty_task"
+      ],
+      "preconditions": [
+        "at least one opportunity signal is present",
+        "no active log_error signals (stability first)"
+      ],
+      "strategy": [
+        "Extract opportunity signals and identify the specific user need or system gap",
+        "Search existing Genes and Capsules for partial matches (avoid reinventing)",
+        "Design a minimal, testable implementation plan (prefer small increments)",
+        "Estimate blast radius; innovate changes may touch more files but must stay within constraints",
+        "Implement the change with clear validation criteria",
+        "Validate using declared validation steps; rollback on failure",
+        "Solidify: record EvolutionEvent with intent=innovate, create new Gene if pattern is novel, create Capsule on success"
+      ],
+      "constraints": {
+        "max_files": 25,
+        "forbidden_paths": [
+          ".git",
+          "node_modules"
+        ]
+      },
+      "validation": [
+        "node scripts/validate-modules.js ./src/evolve ./src/gep/solidify ./src/gep/policyCheck ./src/gep/mutation ./src/gep/personality",
+        "node scripts/validate-suite.js"
+      ]
+    },
+    {
+      "type": "Gene",
+      "id": "gene_gep_optimize_tool_usage",
+      "summary": "Optimize tool execution patterns by reducing redundant exec calls, improving tool selection strategy, and enforcing tool-use constraints to prevent bypass.",
+      "category": "optimize",
+      "signals_match": [
+        "high_tool_usage:exec",
+        "repeated_tool_usage:exec",
+        "tool_bypass|工具绕过|ツール迂回|도구우회",
+        "tool_loop|工具循环|ツールループ|도구반복",
+        "high_tool_usage"
+      ],
+      "preconditions": [
+        "agent repeatedly invokes the same tool (especially exec) without progress",
+        "tool execution bypass patterns detected",
+        "no active error signals (errors would take repair priority)"
+      ],
+      "strategy": [
+        "Analyze tool usage patterns to identify the root cause of repetition (wrong tool, missing context, or lack of guardrails)",
+        "Introduce strategy-level guardrails: prefer single-shot commands, batch related operations, add explicit retry limits",
+        "If tool_bypass detected, strengthen constraint enforcement in prompt assembly or tool routing",
+        "Estimate blast radius; changes should target tool routing, prompt constraints, or signal deduplication logic",
+        "Validate by confirming no regressions in existing tool tests and signal extraction accuracy",
+        "Solidify: record EvolutionEvent with intent=optimize, update Capsule on success"
+      ],
+      "constraints": {
+        "max_files": 15,
+        "forbidden_paths": [
+          ".git",
+          "node_modules"
+        ]
+      },
+      "validation": [
+        "node scripts/validate-modules.js ./src/gep/signals ./src/evolve",
+        "node scripts/validate-suite.js"
+      ],
+      "routing_hint": {
+        "tier": "mid",
+        "reasoning_level": "medium"
+      }
+    },
+    {
+      "type": "Gene",
+      "id": "gene_distilled_s2g-env-vars",
+      "summary": "Vercel environment variable expert guidance. Use when working with .env files, vercel env commands, OIDC tokens, or managing environment-specific configuration.",
+      "category": "optimize",
+      "signals_match": [
+        "use_when_working_with",
+        "env_files",
+        "vercel_env_commands",
+        "oidc_tokens",
+        "vercel_env_pull",
+        "env_local_overwrite",
+        "oidc_token_expiry",
+        "dotenv_cli"
+      ],
+      "preconditions": [
+        "Skill env-vars has just been executed locally"
+      ],
+      "strategy": [
+        "Identify the dominant trigger signals from the Skill description.",
+        "Apply the smallest targeted change that satisfies the Skill workflow.",
+        "Run the Skill validation commands and abort if any fails."
+      ],
+      "constraints": {
+        "max_files": 12,
+        "forbidden_paths": [
+          ".git",
+          "node_modules"
+        ]
+      },
+      "validation": [
+        "node --version"
+      ],
+      "routing_hint": {
+        "tier": "cheap",
+        "reasoning_level": "low"
+      },
+      "schema_version": "1.6.0",
+      "_source": {
+        "kind": "skill2gep",
+        "skill_name": "env-vars",
+        "skill_platform": "vercel",
+        "skill_hash": "ba0bdb4db2",
+        "rationale_paper": "Wang, Ren, Zhang. From Procedural Skills to Strategy Genes. arXiv:2604.15097",
+        "paper_scope": "code-science (arXiv:2604.15097, 45 tasks, Gemini 3.1 Pro/Flash Lite)",
+        "claims_outside_scope": "assumption",
+        "quality_heuristics": {
+          "strategy_steps": 0,
+          "avoid_count": 0,
+          "validation_declared_count": 0,
+          "validation_runnable_count": 0,
+          "validation_fallback_used": true,
+          "signals_extracted": 4,
+          "preconditions_extracted": 0
+        }
+      },
+      "asset_id": "sha256:1501bc37fbefb18630c4dc8a95d8cdc1ed32bec4a465dc3223280ae907e07297"
+    },
+    {
+      "type": "Gene",
+      "id": "gene_tool_integrity",
+      "category": "repair",
+      "signals_match": [
+        "tool_bypass|工具绕过|ツール迂回|도구우회"
+      ],
+      "preconditions": [
+        "agent used shell/exec to perform an action that a registered tool can handle"
+      ],
+      "strategy": [
+        "Always prefer registered tools over ad-hoc scripts or shell workarounds",
+        "If a registered tool fails, report the actual error honestly and attempt to fix the root cause",
+        "Never fabricate explanations -- describe actual actions transparently",
+        "Do not create temporary scripts in extension or project directories"
+      ],
+      "constraints": {
+        "max_files": 4,
+        "forbidden_paths": [
+          ".git",
+          "node_modules"
+        ]
+      },
+      "validation": [
+        "node scripts/validate-suite.js"
+      ],
+      "anti_patterns": [
+        "tool_bypass"
+      ],
+      "routing_hint": {
+        "tier": "cheap",
+        "reasoning_level": "low"
+      }
+    }
+  ]
+}

package/index.js

@@ -491,10 +491,11 @@ async function main() {
           console.warn('[ATP] Auto-init failed: ' + (atpInitErr && atpInitErr.message || atpInitErr));
         }
 
-        // ATP: capability-gap auto-buyer. Default ON as of ATP liquidity
-        // unlock; disable with EVOLVER_ATP_AUTOBUY=off. Also starts the
-        // merchant-side auto-deliver daemon so claimed ATP tasks actually
-        // call submitDelivery and settle instead of expiring.
+        // ATP: capability-gap auto-buyer. OPT-IN as of consent-required
+        // change — new installs do not auto-spend until the user explicitly
+        // runs `evolver atp enable` or answers `y` at the first-run prompt.
+        // Also starts the merchant-side auto-deliver daemon so claimed ATP
+        // tasks actually call submitDelivery and settle instead of expiring.
         try {
           try {
             const { runPrompt } = require('./src/atp/cliAutobuyPrompt');
@@ -502,16 +503,31 @@ async function main() {
           } catch (promptErr) {
             console.warn('[ATP-AutoBuyer] first-run prompt failed: ' + (promptErr && promptErr.message || promptErr));
           }
-          const autoBuyRaw = (process.env.EVOLVER_ATP_AUTOBUY || 'on').toLowerCase().trim();
-          const autoBuyOn = autoBuyRaw !== 'off' && autoBuyRaw !== '0' && autoBuyRaw !== 'false';
-          if (autoBuyOn) {
+          const { autoBuyer } = require('./src/atp');
+          const consent = autoBuyer.getConsent();
+          if (consent.enabled) {
             const hubUrl = process.env.A2A_HUB_URL || process.env.EVOMAP_HUB_URL || '';
             if (hubUrl) {
-              const { autoBuyer } = require('./src/atp');
               autoBuyer.start({
                 dailyCap: Number(process.env.ATP_AUTOBUY_DAILY_CAP_CREDITS) || undefined,
                 perOrderCap: Number(process.env.ATP_AUTOBUY_PER_ORDER_CAP_CREDITS) || undefined,
               });
+              if (consent.source === 'default') {
+                // First-run on a non-TTY (daemon, hook, CI) where the prompt
+                // could not fire AND no env override + no ack file. autoBuyer
+                // is starting with the default-on policy — surface a single
+                // WARN per process so users see what is happening and how to
+                // opt out, instead of discovering it via a credit balance dip.
+                let safeHubUrl;
+                try { safeHubUrl = new URL(hubUrl).origin; }
+                catch { safeHubUrl = '(configured)'; }
+                console.warn('[ATP-AutoBuyer] ATP auto-spend is ON (default for new installs).');
+                console.warn('               Hub: ' + safeHubUrl + '  Caps: ' +
+                  (process.env.ATP_AUTOBUY_DAILY_CAP_CREDITS || '50') + ' credits/day, ' +
+                  (process.env.ATP_AUTOBUY_PER_ORDER_CAP_CREDITS || '10') + '/order' +
+                  ' (cold-start half-cap for the first 5 min).');
+                console.warn('               To opt out: evolver atp disable  (or EVOLVER_ATP_AUTOBUY=off)');
+              }
             } else {
               console.warn('[ATP-AutoBuyer] autobuy enabled but no hub URL configured, skipping.');
             }
@@ -1815,7 +1831,7 @@ async function main() {
       process.exit(1);
     }
 
-  } else if (command === 'buy' || command === 'orders' || command === 'verify') {
+  } else if (command === 'buy' || command === 'orders' || command === 'verify' || command === 'atp') {
     try {
       const atpCli = require('./src/atp/cli');
       const subArgs = args.slice(1); // drop the command token (e.g. "buy") itself
@@ -1827,9 +1843,12 @@ async function main() {
       } else if (command === 'orders') {
         parsed = atpCli.parseOrdersArgs(subArgs);
         runner = atpCli.runOrders;
-      } else {
+      } else if (command === 'verify') {
         parsed = atpCli.parseVerifyArgs(subArgs);
         runner = atpCli.runVerify;
+      } else {
+        parsed = atpCli.parseAtpArgs(subArgs);
+        runner = atpCli.runAtp;
       }
       if (!parsed.ok) {
         console.error('[ATP] ' + parsed.error);
@@ -1844,7 +1863,7 @@ async function main() {
     }
 
   } else {
-    console.log(`Usage: node index.js [run|/evolve|solidify|review|distill|fetch|sync|asset-log|webui|setup-hooks|buy|orders|verify|atp-complete] [--loop]
+    console.log(`Usage: node index.js [run|/evolve|solidify|review|distill|fetch|sync|asset-log|webui|setup-hooks|buy|orders|verify|atp|atp-complete] [--loop]
   - fetch flags:
     - --skill=<id> | -s <id>   (skill ID to download)
     - --out=<dir>              (output directory, default: ./skills/<skill_id>)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@evomap/evolver",
-  "version": "1.87.1",
+  "version": "1.87.2",
   "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": {

package/src/atp/autoBuyer.js

@@ -1,12 +1,19 @@
-// ATP Auto-Buyer (opt-out, default ON as of ATP liquidity unlock)
+// ATP Auto-Buyer (opt-in: requires explicit consent before auto-spending)
 // Converts capability gaps into ATP orders with strict budget caps and
-// 24h question-level deduplication. Disable by setting
-// EVOLVER_ATP_AUTOBUY=off. Budget caps:
+// 24h question-level deduplication. Budget caps:
 //   ATP_AUTOBUY_DAILY_CAP_CREDITS     (default 50)
 //   ATP_AUTOBUY_PER_ORDER_CAP_CREDITS (default 10)
 // Cold-start safety: the first 5 minutes after process start use a half-cap
 // to protect against misconfiguration loops on restart storms.
 //
+// Consent resolution (in order):
+//   1. EVOLVER_ATP_AUTOBUY=on|off env — explicit operator override wins.
+//   2. ack file at <memory>/atp-autobuy-ack.json with `{enabled: bool}` —
+//      written by first-run prompt (cliAutobuyPrompt) or `evolver atp
+//      enable|disable`.
+//   3. No signal → OFF. New installs never auto-spend before the user has
+//      explicitly opted in (consumer protection: ATP spends real credits).
+//
 // Integration contract:
 //   1) Call start({ dailyCap, perOrderCap }) once at Evolver boot. The
 //      evolve loop does this at the top of every cycle; start() is
@@ -31,6 +38,7 @@ const DEFAULT_ORDER_TIMEOUT_MS = 3000;
 const COLD_START_WINDOW_MS = 5 * 60 * 1000;
 const DEDUP_TTL_MS = 24 * 60 * 60 * 1000;
 const LEDGER_FILENAME = 'atp-autobuyer-ledger.json';
+const ACK_FILENAME = 'atp-autobuy-ack.json';
 
 let _started = false;
 let _startedAt = 0;
@@ -44,18 +52,57 @@ function _ledgerPath() {
   return path.join(getMemoryDir(), LEDGER_FILENAME);
 }
 
+function _ackPath() {
+  return path.join(getMemoryDir(), ACK_FILENAME);
+}
+
 function _todayKey(now) {
   const d = new Date(typeof now === 'number' ? now : Date.now());
   return d.toISOString().slice(0, 10); // UTC YYYY-MM-DD
 }
 
-function _isEnabled() {
-  // Default ON: the evolve loop starts autoBuyer at the top of every cycle
-  // so new users get ATP buyer routing out of the box. Disable by setting
-  // EVOLVER_ATP_AUTOBUY=off. Budget caps (DAILY_CAP + PER_ORDER_CAP) keep
-  // the downside bounded even when this is on.
-  const raw = (process.env.EVOLVER_ATP_AUTOBUY || 'on').toLowerCase().trim();
-  return raw !== 'off' && raw !== '0' && raw !== 'false';
+function _readAck() {
+  try {
+    const p = _ackPath();
+    if (!fs.existsSync(p)) return null;
+    const parsed = JSON.parse(fs.readFileSync(p, 'utf8'));
+    if (!parsed || typeof parsed !== 'object') return null;
+    if (typeof parsed.enabled !== 'boolean') return null;
+    return parsed;
+  } catch (_) {
+    return null;
+  }
+}
+
+// Resolve consent. Returns:
+//   { enabled: true,  source: 'env'|'ack'|'default' }
+//   { enabled: false, source: 'env'|'ack' }
+// The `default` case is the new-install path (no env override, no ack file):
+// auto-spend defaults ON, gated by the daily/per-order caps and the cold-start
+// half-cap window. The first-run prompt and `evolver atp disable` remain the
+// opt-out paths for users who do not want auto-spend; once an explicit ack is
+// recorded the source flips to 'ack' and the user's choice (either way) wins
+// over this default.
+function getConsent() {
+  const envRaw = process.env.EVOLVER_ATP_AUTOBUY;
+  if (typeof envRaw === 'string') {
+    // Trim BEFORE the length check so whitespace-only values
+    // (e.g. EVOLVER_ATP_AUTOBUY=" ") count as unset, matching the
+    // classify() helper in cliAutobuyPrompt.js. Without this alignment a
+    // whitespace value would skip the prompt in classify (treats as unset
+    // → 'eligible') but still enter this env branch, trim to "", fail to
+    // match 'off'/'0'/'false', and silently return enabled=true.
+    const s = envRaw.trim().toLowerCase();
+    if (s.length > 0) {
+      const enabled = s !== 'off' && s !== '0' && s !== 'false';
+      return { enabled, source: 'env' };
+    }
+  }
+  const ack = _readAck();
+  if (ack) {
+    return { enabled: ack.enabled === true, source: 'ack' };
+  }
+  return { enabled: true, source: 'default' };
 }
 
 function _emptyLedger() {
@@ -125,7 +172,8 @@ function _effectiveCap(value, now) {
 
 function start(opts) {
   if (_started) return;
-  if (!_isEnabled()) return;
+  const consent = getConsent();
+  if (!consent.enabled) return;
   _started = true;
   _startedAt = Date.now();
   const dailyCap = Math.max(0, Math.floor(Number((opts && opts.dailyCap) || process.env.ATP_AUTOBUY_DAILY_CAP_CREDITS) || DEFAULT_DAILY_CAP));
@@ -213,6 +261,24 @@ async function considerOrder(opts) {
   return { ok: false, error: (result && result.error) || 'unknown_error' };
 }
 
+// Write the consent ack file. Used by `evolver atp enable|disable` and the
+// first-run prompt. `enabled=true` persists opt-in; `enabled=false` persists
+// explicit opt-out so the prompt does not re-ask next session. Atomic write
+// via .tmp + rename so a crash mid-write never produces a corrupt ack file.
+function setConsent(enabled) {
+  const dir = getMemoryDir();
+  try { if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true }); } catch (_) {}
+  const body = {
+    enabled: !!enabled,
+    acknowledged_at: new Date().toISOString(),
+    version: 1,
+  };
+  const tmp = _ackPath() + '.tmp';
+  fs.writeFileSync(tmp, JSON.stringify(body, null, 2) + '\n', 'utf8');
+  fs.renameSync(tmp, _ackPath());
+  return body;
+}
+
 // Test-only reset, not exported by default.
 function _resetForTests() {
   _started = false;
@@ -225,10 +291,20 @@ function _resetForTests() {
 }
 
 module.exports = {
+  // Lifecycle.
   start,
   stop,
   isStarted,
   considerOrder,
+  // Consent surface — public API. Production callers (CLI runAtp,
+  // cliAutobuyPrompt, the daemon run loop) MUST use these, not the
+  // __internals duplicates below, so the "test-only" contract on
+  // __internals stays honest (Bugbot PR #141 R6).
+  getConsent,
+  setConsent,
+  getAckPath: _ackPath,
+  readAck: _readAck,
+  ACK_FILENAME,
   // Exposed for tests and diagnostics only; callers should not depend on
   // these internals in production code paths.
   __internals: {
@@ -237,12 +313,15 @@ module.exports = {
     questionHash: _questionHash,
     effectiveCap: _effectiveCap,
     resetForTests: _resetForTests,
+    ackPath: _ackPath,
+    readAck: _readAck,
     constants: {
       DEFAULT_DAILY_CAP,
       DEFAULT_PER_ORDER_CAP,
       COLD_START_WINDOW_MS,
       DEDUP_TTL_MS,
       LEDGER_FILENAME,
+      ACK_FILENAME,
     },
   },
 };

package/src/atp/cli.js

@@ -118,6 +118,27 @@ function parseVerifyArgs(args) {
   return { ok: true, opts: { orderId, action } };
 }
 
+// `evolver atp <enable|disable|status>` — manage autoBuyer consent ack file.
+// Non-TTY users (daemon, CI, hooks) opt in here instead of the interactive
+// first-run prompt. Returns { ok, opts: { sub } } or { ok: false, error }.
+function parseAtpArgs(args) {
+  if (!Array.isArray(args) || args.length === 0) {
+    return { ok: false, error: 'atp requires <enable|disable|status>' };
+  }
+  let sub = null;
+  for (let i = 0; i < args.length; i++) {
+    const a = args[i];
+    if (typeof a === 'string' && !a.startsWith('--')) {
+      sub = a.toLowerCase();
+      break;
+    }
+  }
+  if (!sub || !['enable', 'disable', 'status'].includes(sub)) {
+    return { ok: false, error: 'atp subcommand must be enable|disable|status (got: ' + sub + ')' };
+  }
+  return { ok: true, opts: { sub } };
+}
+
 async function runBuy(opts, deps) {
   const atp = (deps && deps.atp) || require('./index');
   const consumerAgent = atp.consumerAgent;
@@ -226,6 +247,80 @@ async function runVerify(opts, deps) {
   }
 }
 
+// Subcommand runner for `evolver atp enable|disable|status`. Writes the ack
+// file via autoBuyer.setConsent so subsequent daemon starts pick it up. Does
+// NOT mutate process.env — env override wins over the ack file by design,
+// and we don't want a transient CLI invocation to silently shadow operator
+// shell config.
+// Detect whether an EVOLVER_ATP_AUTOBUY env override is currently set AND
+// would supersede the ack we are about to write. Returns the effective env
+// boolean (true=on, false=off) or null if env is unset / whitespace-only.
+// Mirrors the trim-before-length-check rule from autoBuyer.getConsent so
+// the CLI and the runtime agree on what "set" means (Bugbot PR #141).
+function _envOverride() {
+  const raw = process.env.EVOLVER_ATP_AUTOBUY;
+  if (typeof raw !== 'string') return null;
+  const s = raw.trim().toLowerCase();
+  if (s.length === 0) return null;
+  return !(s === 'off' || s === '0' || s === 'false');
+}
+
+async function runAtp(opts, deps) {
+  const autoBuyer = (deps && deps.autoBuyer) || require('./autoBuyer');
+  const log = (deps && deps.log) || console.log;
+  const err = (deps && deps.err) || console.error;
+
+  try {
+    if (opts.sub === 'enable') {
+      const body = autoBuyer.setConsent(true);
+      log('[ATP] auto-spend ENABLED (consent recorded ' + body.acknowledged_at + ').');
+      log('      Caps: daily=' + (process.env.ATP_AUTOBUY_DAILY_CAP_CREDITS || '50') +
+          ', per-order=' + (process.env.ATP_AUTOBUY_PER_ORDER_CAP_CREDITS || '10') + ' credits.');
+      log('      Disable: evolver atp disable  (or  EVOLVER_ATP_AUTOBUY=off)');
+      // Loud warning if an env override will silently undo the ack at
+      // runtime. Bugbot PR #141 Medium: without this the user gets a
+      // false confirmation and real credits keep flowing the wrong way.
+      const envEnabled = _envOverride();
+      if (envEnabled === false) {
+        log('');
+        log('[ATP] WARNING: EVOLVER_ATP_AUTOBUY=' + process.env.EVOLVER_ATP_AUTOBUY +
+            ' is set in your environment and will OVERRIDE the ack file at runtime.');
+        log('      Auto-spend will stay OFF until you unset it (env wins over the ack file).');
+        return { exitCode: 0, data: body, envOverride: 'off' };
+      }
+      return { exitCode: 0, data: body };
+    }
+    if (opts.sub === 'disable') {
+      const body = autoBuyer.setConsent(false);
+      log('[ATP] auto-spend DISABLED (consent recorded ' + body.acknowledged_at + ').');
+      log('      Re-enable: evolver atp enable');
+      const envEnabled = _envOverride();
+      if (envEnabled === true) {
+        log('');
+        log('[ATP] WARNING: EVOLVER_ATP_AUTOBUY=' + process.env.EVOLVER_ATP_AUTOBUY +
+            ' is set in your environment and will OVERRIDE the ack file at runtime.');
+        log('      Auto-spend will stay ON (and continue charging credits) until you unset it.');
+        return { exitCode: 0, data: body, envOverride: 'on' };
+      }
+      return { exitCode: 0, data: body };
+    }
+    // status
+    const consent = autoBuyer.getConsent();
+    const ackPath = autoBuyer.getAckPath();
+    log('[ATP] auto-spend: ' + (consent.enabled ? 'ENABLED' : 'DISABLED') +
+        '  (source: ' + consent.source + ')');
+    log('      ack file: ' + ackPath);
+    if (consent.source === 'default') {
+      log('      Default policy (no ack file, no env override). Run `evolver atp disable`');
+      log('      to opt out, or `evolver atp enable` to record explicit opt-in.');
+    }
+    return { exitCode: 0, data: consent };
+  } catch (e) {
+    err('[ATP] atp command error: ' + (e && e.message || e));
+    return { exitCode: 1, error: String(e) };
+  }
+}
+
 function printUsage() {
   return [
     'ATP subcommands:',
@@ -234,6 +329,7 @@ function printUsage() {
     '  evolver orders [--role=consumer|merchant] [--status=pending|verified|disputed|settled]',
     '                 [--limit=N] [--json]',
     '  evolver verify <orderId> [--action=confirm|ai_judge]',
+    '  evolver atp <enable|disable|status>   -- manage auto-spend consent',
   ].join('\n');
 }
 
@@ -241,8 +337,10 @@ module.exports = {
   parseBuyArgs,
   parseOrdersArgs,
   parseVerifyArgs,
+  parseAtpArgs,
   runBuy,
   runOrders,
   runVerify,
+  runAtp,
   printUsage,
 };