@evomap/evolver 1.87.0 → 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

@@ -390,11 +390,11 @@ async function main() {
         // own env, since verification can run with HubMirror off (verifier
         // events are local-only on first ship).
         try {
-          const enabled = String(process.env.EVOLVE_RECALL_VERIFY || '1') !== '0';
+          const enabled = String(process.env.EVOLVE_RECALL_VERIFY || '0') === '1';
           const sampleRateRaw = Number(process.env.EVOLVE_RECALL_VERIFY_SAMPLE_RATE);
           const sampleRate = Number.isFinite(sampleRateRaw) && sampleRateRaw >= 0 && sampleRateRaw <= 1 ? sampleRateRaw : 1.0;
           if (!enabled) {
-            console.log('[RecallVerify] DISABLED — set EVOLVE_RECALL_VERIFY=1 to verify published assets round-trip via Hub Phase 2 lookup.');
+            console.log('[RecallVerify] DISABLED (default) — opt-in observability only. Set EVOLVE_RECALL_VERIFY=1 to verify published assets round-trip via Hub Phase 2 lookup.');
           } else {
             console.log(`[RecallVerify] ENABLED — verifying published assets via Hub Phase 2 lookup, sample_rate=${sampleRate}. Set EVOLVE_RECALL_VERIFY=0 to disable.`);
           }
@@ -451,7 +451,7 @@ async function main() {
         // RecallVerify worker: starts once per process; drains the publish-
         // verification queue with backoff. unref'd so it never blocks exit.
         try {
-          if (String(process.env.EVOLVE_RECALL_VERIFY || '1') !== '0') {
+          if (String(process.env.EVOLVE_RECALL_VERIFY || '0') === '1') {
             require('./src/gep/recallVerifier').startWorker();
           }
         } catch (rvStartErr) {
@@ -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.0",
+  "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/adapters/hookAdapter.js

@@ -153,12 +153,21 @@ function assertNotSymlink(p, label) {
 
 function copyHookScripts(destDir, evolverRoot) {
   const scriptsDir = path.join(evolverRoot || __dirname, 'scripts');
-  // _runtimePaths.js is required by the two session-* scripts via
-  // `require('./_runtimePaths')`, which resolves relative to the *destination*
-  // (__dirname after copy). It MUST be copied alongside or both hooks crash
-  // with MODULE_NOT_FOUND at runtime. Caught in PR #94 review.
+  // Every helper required by the entry-point hooks via `require('./_xxx')`
+  // resolves relative to the *destination* (`__dirname` after copy), so
+  // every such helper MUST appear here or the hook crashes with
+  // MODULE_NOT_FOUND at runtime. Two regressions of this shape have shipped
+  // already:
+  //   - PR #94 review caught `_runtimePaths.js` missing from this list.
+  //   - Issue #547 (rendigua, v1.87.0): `_memoryFiltering.js` was added to
+  //     evolver-session-start.js but not here, so fresh installs failed
+  //     immediately on `node .codex/hooks/evolver-session-start.js`.
+  // To keep future helpers from re-living this, the regression test in
+  // test/adapters.test.js scans every `require('./_*')` in the source
+  // adapter scripts and asserts the target file is in this list.
   const scripts = [
     '_runtimePaths.js',
+    '_memoryFiltering.js',
     'evolver-session-start.js',
     'evolver-signal-detect.js',
     'evolver-session-end.js',
@@ -235,8 +244,14 @@ function removeEvolverHooks(filePath, { markerKey = '_evolver_managed' } = {}) {
 }
 
 function removeHookScripts(hooksDir) {
+  // Must mirror the install list above. If install copies a helper but
+  // uninstall doesn't remove it, `setup-hooks --uninstall` leaves orphan
+  // files behind that the user then has to clean up by hand (#547 fix
+  // would have introduced exactly this gap if only the install side
+  // had been updated).
   const scripts = [
     '_runtimePaths.js',
+    '_memoryFiltering.js',
     'evolver-session-start.js',
     'evolver-signal-detect.js',
     'evolver-session-end.js',

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,
     },
   },
 };