@evomap/evolver 1.72.0 → 1.74.1

package/assets/gep/candidates.jsonl

@@ -1,4 +1 @@
-{"type":"CapabilityCandidate","id":"cand_b9a66a5c","title":"Harden session log detection and fallback behavior","source":"signals","created_at":"2026-04-27T10:30:27.039Z","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"}}
-{"type":"CapabilityCandidate","id":"cand_b9a66a5c","title":"Harden session log detection and fallback behavior","source":"signals","created_at":"2026-04-27T10:30:56.391Z","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"}}
-{"type":"CapabilityCandidate","id":"cand_b9a66a5c","title":"Harden session log detection and fallback behavior","source":"signals","created_at":"2026-04-27T10:31:11.248Z","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"}}
-{"type":"CapabilityCandidate","id":"cand_b9a66a5c","title":"Harden session log detection and fallback behavior","source":"signals","created_at":"2026-04-27T10:31:26.375Z","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"}}
+{"type":"CapabilityCandidate","id":"cand_b9a66a5c","title":"Harden session log detection and fallback behavior","source":"signals","created_at":"2026-04-28T10:59:23.012Z","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/index.js

@@ -1072,6 +1072,45 @@ async function main() {
       process.exit(1);
     }
 
+  } else if (command === 'atp-complete') {
+    // Invoked by a spawned Cursor sub-session after it has written the ATP
+    // task answer to a file. Drives publish -> task/complete -> atp/deliver.
+    try {
+      const subArgs = args.slice(1);
+      function flag(name) {
+        const pref = '--' + name + '=';
+        const hit = subArgs.find(function (a) { return typeof a === 'string' && a.startsWith(pref); });
+        return hit ? hit.slice(pref.length) : null;
+      }
+      function list(name) {
+        const raw = flag(name);
+        if (!raw) return null;
+        return raw.split(',').map(function (s) { return String(s).trim(); }).filter(Boolean);
+      }
+      const taskId = flag('task-id');
+      const orderId = flag('order-id');
+      const answerFile = flag('answer-file');
+      const summary = flag('summary');
+      const capabilities = list('capabilities');
+      const signals = list('signals');
+      if (!taskId || !orderId || !answerFile) {
+        console.error('[ATP-Complete] Missing required flags: --task-id, --order-id, --answer-file');
+        console.error('Usage: node index.js atp-complete --task-id=<tid> --order-id=<oid> --answer-file=<path> [--summary="..."] [--capabilities=cap1,cap2] [--signals=sig1,sig2]');
+        process.exit(2);
+      }
+      const { completeAtpTask } = require('./src/atp/atpExecute');
+      const res = await completeAtpTask({ taskId, orderId, answerFile, summary, capabilities, signals });
+      if (res && res.ok) {
+        console.log('[ATP-Complete] OK asset_id=' + res.assetId + (res.deliveryId ? ' delivery_id=' + res.deliveryId : ''));
+        process.exit(0);
+      }
+      console.error('[ATP-Complete] FAILED stage=' + (res && res.stage) + ' error=' + (res && res.error));
+      process.exit(1);
+    } catch (atpCompleteErr) {
+      console.error('[ATP-Complete] Error:', atpCompleteErr && atpCompleteErr.message || atpCompleteErr);
+      process.exit(1);
+    }
+
   } else if (command === 'buy' || command === 'orders' || command === 'verify') {
     try {
       const atpCli = require('./src/atp/cli');
@@ -1101,7 +1140,7 @@ async function main() {
     }
 
   } else {
-    console.log(`Usage: node index.js [run|/evolve|solidify|review|distill|fetch|asset-log|setup-hooks|buy|orders|verify] [--loop]
+    console.log(`Usage: node index.js [run|/evolve|solidify|review|distill|fetch|asset-log|setup-hooks|buy|orders|verify|atp-complete] [--loop]
   - fetch flags:
     - --skill=<id> | -s <id>   (skill ID to download)
     - --out=<dir>              (output directory, default: ./skills/<skill_id>)
@@ -1141,6 +1180,13 @@ async function main() {
     - --json                   (raw JSON)
   - verify <orderId>           (confirm delivery or trigger AI judge)
     - --action=confirm|ai_judge (default confirm)
+  - atp-complete               (internal: spawned Cursor sub-session uses this to settle an ATP task)
+    - --task-id=<tid>          (Hub task id, required)
+    - --order-id=<oid>         (ATP DeliveryProof id, required)
+    - --answer-file=<path>     (file containing the merchant answer, required)
+    - --summary="..."          (capsule summary, optional)
+    - --capabilities=a,b       (listing capabilities, optional)
+    - --signals=s1,s2          (task signals, optional)
 
 Validator role (decentralized validation, default ON since v1.69.0):
   - EVOLVER_VALIDATOR_ENABLED=0    opt out (env beats persisted flag and default)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@evomap/evolver",
-  "version": "1.72.0",
+  "version": "1.74.1",
   "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/atpExecute.js

@@ -0,0 +1,285 @@
+// ATP end-to-end task completer.
+//
+// Invoked from the `atp-complete` subcommand (index.js). A spawned Cursor
+// sub-session answers an ATP task, writes the answer to disk, then runs:
+//
+//   node index.js atp-complete \
+//     --task-id=<tid> --order-id=<oid> --answer-file=<path> [--summary="..."]
+//
+// This module takes that answer and drives the full settlement path:
+//   1. Synthesize a minimal Gene + Capsule bundle wrapping the answer.
+//   2. POST /a2a/publish to register the Capsule asset on the Hub (signed).
+//   3. POST /a2a/task/complete to bind the resultAssetId to the claimed task.
+//   4. POST /a2a/atp/deliver to submit the proof_payload (asset_id + result).
+//
+// Autoverify (verifyMode=auto) on the Hub treats `payload.asset_id` and
+// `payload.result` as has_result=true with pass_rate=1.0, so a valid answer
+// immediately progresses the DeliveryProof from pending -> verified -> settled.
+//
+// Failures are returned as { ok:false, stage:..., error:... } so the caller can
+// retry per-stage without duplicating upstream effects (Gene/Capsule asset_ids
+// are deterministic content-hashes, so republish of the same bundle is
+// idempotent server-side).
+
+const fs = require('fs');
+const http = require('http');
+const https = require('https');
+const crypto = require('crypto');
+
+const { computeAssetId } = require('../gep/contentHash');
+const {
+  getNodeId,
+  getHubUrl,
+  getHubNodeSecret,
+  buildHubHeaders,
+  sendHelloToHub,
+} = require('../gep/a2aProtocol');
+const { submitDelivery } = require('./hubClient');
+
+const MAX_ANSWER_CHARS = 32000; // cap capsule.content to protect Hub payload limits
+const PUBLISH_TIMEOUT_MS = 15000;
+
+function _readAnswer(answerFile) {
+  const raw = fs.readFileSync(answerFile, 'utf8');
+  const trimmed = String(raw || '').trim();
+  if (!trimmed) throw new Error('answer file is empty');
+  if (trimmed.length > MAX_ANSWER_CHARS) {
+    return trimmed.slice(0, MAX_ANSWER_CHARS - 40) + '\n...[TRUNCATED]...';
+  }
+  return trimmed;
+}
+
+function _buildGene(capabilities, signals) {
+  const caps = Array.isArray(capabilities) && capabilities.length > 0
+    ? capabilities.slice(0, 8)
+    : ['general'];
+  const sig = Array.isArray(signals) && signals.length > 0
+    ? signals.slice(0, 8)
+    : ['atp_task'];
+  const gene = {
+    type: 'Gene',
+    schema_version: '1.0',
+    id: 'gene_atp_answer_' + caps.sort().join('_').slice(0, 40),
+    summary: 'Deliver an ATP task answer for capabilities: ' + caps.join(', '),
+    signals_match: sig,
+    category: 'innovate',
+    strategy: [
+      'Read the buyer question carefully and identify the requested capability.',
+      'Produce a concrete, actionable answer addressing the question directly.',
+      'Return the answer as Capsule content for verifiable delivery.',
+    ],
+    validation: [
+      'Answer is non-empty and directly addresses the buyer question.',
+      'Answer references the requested capabilities where relevant.',
+    ],
+  };
+  gene.asset_id = computeAssetId(gene);
+  return gene;
+}
+
+function _buildCapsule({ gene, answer, summary, orderId, taskId, capabilities, signals }) {
+  const caps = Array.isArray(capabilities) ? capabilities.slice(0, 8) : [];
+  const sig = Array.isArray(signals) && signals.length > 0 ? signals.slice(0, 8) : ['atp_task'];
+  const confidence = 0.9; // merchant self-attested; buyer verify may override
+  const capsuleSummary = String(summary || '').trim()
+    || 'ATP merchant delivery for order ' + String(orderId || '').slice(0, 24);
+  const capsule = {
+    type: 'Capsule',
+    schema_version: '1.0',
+    id: 'capsule_atp_' + String(orderId || taskId || Date.now()).replace(/[^a-zA-Z0-9_\-]/g, '_').slice(0, 40),
+    trigger: sig,
+    gene: gene.id,
+    summary: capsuleSummary.slice(0, 200),
+    confidence,
+    blast_radius: { files: 0, lines: Math.min(1000, answer.split('\n').length) },
+    outcome: { status: 'success', score: confidence },
+    env_fingerprint: { platform: process.platform, arch: process.arch, runtime: 'evolver-atp' },
+    content: answer,
+    source_type: 'atp_task_executor',
+    atp: {
+      order_id: orderId || null,
+      task_id: taskId || null,
+      capabilities: caps,
+    },
+  };
+  capsule.asset_id = computeAssetId(capsule);
+  return capsule;
+}
+
+function _publishUrl() {
+  const base = String(getHubUrl() || '').replace(/\/+$/, '');
+  if (!base) throw new Error('hub url not configured');
+  return base + '/a2a/publish';
+}
+
+function _postJson(urlStr, body, timeoutMs) {
+  return new Promise(function (resolve) {
+    let parsed;
+    try {
+      parsed = new URL(urlStr);
+    } catch (e) {
+      resolve({ ok: false, error: 'invalid_url: ' + (e && e.message) });
+      return;
+    }
+    const isHttps = parsed.protocol === 'https:';
+    const lib = isHttps ? https : http;
+    const payload = JSON.stringify(body || {});
+    const headers = Object.assign(
+      { 'Content-Type': 'application/json', 'Content-Length': Buffer.byteLength(payload) },
+      buildHubHeaders() || {},
+    );
+    const req = lib.request(
+      {
+        hostname: parsed.hostname,
+        port: parsed.port || (isHttps ? 443 : 80),
+        path: parsed.pathname + (parsed.search || ''),
+        method: 'POST',
+        headers: headers,
+        timeout: timeoutMs || PUBLISH_TIMEOUT_MS,
+      },
+      function (res) {
+        const chunks = [];
+        res.on('data', function (c) { chunks.push(c); });
+        res.on('end', function () {
+          const text = Buffer.concat(chunks).toString('utf8');
+          let data = null;
+          try { data = text ? JSON.parse(text) : null; } catch (e) { data = { raw: text }; }
+          if (res.statusCode >= 200 && res.statusCode < 300) {
+            resolve({ ok: true, status: res.statusCode, data });
+          } else {
+            resolve({ ok: false, status: res.statusCode, data, error: 'http_' + res.statusCode });
+          }
+        });
+      },
+    );
+    req.on('timeout', function () { req.destroy(new Error('timeout')); });
+    req.on('error', function (err) { resolve({ ok: false, error: err.message }); });
+    req.write(payload);
+    req.end();
+  });
+}
+
+async function _ensureNodeSecret() {
+  if (getHubNodeSecret()) return true;
+  try {
+    const hello = await sendHelloToHub();
+    return !!(hello && hello.ok);
+  } catch (e) {
+    return false;
+  }
+}
+
+async function _publishBundle(gene, capsule) {
+  const nodeSecret = getHubNodeSecret();
+  if (!nodeSecret) return { ok: false, error: 'missing_node_secret_after_hello' };
+  const signatureInput = [gene.asset_id, capsule.asset_id].sort().join('|');
+  const signature = crypto.createHmac('sha256', nodeSecret).update(signatureInput).digest('hex');
+  const msg = {
+    protocol: 'gep-a2a',
+    protocol_version: '1.0.0',
+    message_type: 'publish',
+    message_id: 'msg_atp_' + crypto.randomBytes(8).toString('hex'),
+    timestamp: new Date().toISOString(),
+    sender_id: getNodeId(),
+    payload: { assets: [gene, capsule], signature: signature },
+  };
+  return _postJson(_publishUrl(), msg, PUBLISH_TIMEOUT_MS);
+}
+
+async function _completeTaskOnHub(taskId, assetId) {
+  const base = String(getHubUrl() || '').replace(/\/+$/, '');
+  if (!base) return { ok: false, error: 'hub_url_missing' };
+  return _postJson(base + '/a2a/task/complete', {
+    task_id: taskId,
+    asset_id: assetId,
+    node_id: getNodeId(),
+  }, PUBLISH_TIMEOUT_MS);
+}
+
+/**
+ * End-to-end ATP task completion driver.
+ *
+ * @param {object} opts
+ * @param {string} opts.taskId     - Hub task row id (required)
+ * @param {string} opts.orderId    - ATP DeliveryProof id (required)
+ * @param {string} opts.answerFile - Path to file holding the merchant answer (required)
+ * @param {string} [opts.summary]  - Short summary for capsule.summary
+ * @param {string[]} [opts.capabilities] - Listing capabilities (metadata only)
+ * @param {string[]} [opts.signals]      - Task signals (metadata only)
+ * @returns {Promise<{ok:boolean, stage?:string, error?:string, assetId?:string}>}
+ */
+async function completeAtpTask(opts) {
+  const taskId = opts && opts.taskId;
+  const orderId = opts && opts.orderId;
+  const answerFile = opts && opts.answerFile;
+  if (!taskId || !orderId || !answerFile) {
+    return { ok: false, stage: 'input', error: 'taskId, orderId, answerFile are required' };
+  }
+
+  let answer;
+  try {
+    answer = _readAnswer(answerFile);
+  } catch (e) {
+    return { ok: false, stage: 'read_answer', error: e && e.message };
+  }
+
+  const handshakeOk = await _ensureNodeSecret();
+  if (!handshakeOk) {
+    return { ok: false, stage: 'hello', error: 'failed to register with hub; node_secret missing' };
+  }
+
+  const gene = _buildGene(opts.capabilities, opts.signals);
+  const capsule = _buildCapsule({
+    gene,
+    answer,
+    summary: opts.summary,
+    orderId,
+    taskId,
+    capabilities: opts.capabilities,
+    signals: opts.signals,
+  });
+
+  const pub = await _publishBundle(gene, capsule);
+  if (!pub.ok) {
+    return { ok: false, stage: 'publish', error: pub.error || 'publish_failed', details: pub };
+  }
+  const decision = pub.data && pub.data.payload && pub.data.payload.decision;
+  if (decision && decision !== 'accept') {
+    const reason = pub.data.payload.reason || 'unknown';
+    return { ok: false, stage: 'publish', error: 'publish_rejected: ' + reason, details: pub.data };
+  }
+
+  const complete = await _completeTaskOnHub(taskId, capsule.asset_id);
+  if (!complete.ok) {
+    return { ok: false, stage: 'complete', error: complete.error || 'complete_failed', details: complete };
+  }
+
+  const proofPayload = {
+    asset_id: capsule.asset_id,
+    result: capsule.summary,
+    content_hash: capsule.asset_id,
+    pass_rate: 1.0,
+    delivered_by: getNodeId(),
+    task_id: taskId,
+  };
+
+  const delivery = await submitDelivery(orderId, proofPayload);
+  if (!delivery || !delivery.ok) {
+    return {
+      ok: false,
+      stage: 'deliver',
+      error: (delivery && delivery.error) || 'deliver_failed',
+      assetId: capsule.asset_id,
+      details: delivery,
+    };
+  }
+
+  return { ok: true, assetId: capsule.asset_id, deliveryId: delivery.data && delivery.data.proof_id };
+}
+
+module.exports = {
+  completeAtpTask,
+  // exported for tests
+  _buildGene,
+  _buildCapsule,
+};

package/src/atp/atpTaskPickup.js

@@ -0,0 +1,233 @@
+// ATP Task Pickup (merchant-side)
+//
+// When a buyer places an ATP order, the Hub creates a Task row in status
+// "claimed" already bound to a target merchant node (see orderRouterService).
+// That Task never appears in /a2a/fetch (which only returns status="open"
+// tasks), so without this module the merchant's Evolver runtime never knows
+// it has work to do, no resultAssetId is ever written, autoDeliver never
+// runs, and the DeliveryProof expires after 7 days.
+//
+// This module bridges the gap by:
+//   1. Polling /a2a/task/my for tasks with atp_order_id set and no
+//      result_asset_id yet (the "merchant owes work" shape).
+//   2. Producing a renderable sessions_spawn(...) prompt that the main loop
+//      can emit to stdout. The Evolver wrapper (Cursor/Claude Code hook)
+//      picks that up and launches a sub-session that answers the question
+//      and runs `node index.js atp-complete` to settle the order.
+//   3. Deduping via a local ledger so the same task is never spawned twice,
+//      even across restarts.
+//
+// The module never *itself* prints sessions_spawn. It only PROVIDES the
+// spawn string to whoever orchestrates stdout (evolve.js main loop), so the
+// existing "one sessions_spawn per cycle" contract with the wrapper is
+// preserved and evolve's normal bridge is not interfered with.
+
+const fs = require('fs');
+const path = require('path');
+
+const { getMemoryDir } = require('../gep/paths');
+const { renderSessionsSpawnCall } = require('../gep/bridge');
+const hubClient = require('./hubClient');
+
+const LEDGER_FILENAME = 'atp-pickup-ledger.json';
+const LEDGER_MAX_ENTRIES = 500;
+const SPAWN_COOLDOWN_MS = 5 * 60 * 1000; // do not respawn the same task within 5 min
+const MAX_ANSWER_PROMPT_CHARS = 12000;
+
+function _isEnabled() {
+  const raw = (process.env.EVOLVER_ATP_PICKUP || 'on').toLowerCase().trim();
+  return raw !== 'off' && raw !== '0' && raw !== 'false';
+}
+
+function _ledgerPath() {
+  return path.join(getMemoryDir(), LEDGER_FILENAME);
+}
+
+function _emptyLedger() {
+  return { version: 1, spawned: {} };
+}
+
+function _readLedger() {
+  try {
+    const p = _ledgerPath();
+    if (!fs.existsSync(p)) return _emptyLedger();
+    const raw = fs.readFileSync(p, 'utf8');
+    const parsed = JSON.parse(raw);
+    if (!parsed || typeof parsed !== 'object' || !parsed.spawned) return _emptyLedger();
+    return parsed;
+  } catch (_) {
+    return _emptyLedger();
+  }
+}
+
+function _writeLedger(ledger) {
+  try {
+    const dir = getMemoryDir();
+    if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
+    const entries = Object.entries(ledger.spawned || {});
+    if (entries.length > LEDGER_MAX_ENTRIES) {
+      ledger.spawned = Object.fromEntries(entries.slice(-LEDGER_MAX_ENTRIES));
+    }
+    const tmp = _ledgerPath() + '.tmp';
+    fs.writeFileSync(tmp, JSON.stringify(ledger, null, 2));
+    fs.renameSync(tmp, _ledgerPath());
+  } catch (_) {
+    // Non-fatal: next tick will re-read Hub state. Stale ledger at worst
+    // causes a duplicate spawn, which the Hub will 409 on already-completed
+    // tasks without side effects.
+  }
+}
+
+function _isEligible(task) {
+  if (!task || typeof task !== 'object') return false;
+  if (!task.atp_order_id) return false;
+  if (task.result_asset_id) return false;
+  if (task.status && task.status !== 'claimed' && task.status !== 'open') return false;
+  if (!task.id) return false;
+  return true;
+}
+
+function _recentlySpawned(ledger, taskId) {
+  const entry = ledger.spawned && ledger.spawned[taskId];
+  if (!entry || typeof entry !== 'object') return false;
+  const ts = Number(entry.at) || 0;
+  return Date.now() - ts < SPAWN_COOLDOWN_MS;
+}
+
+function _clipQuestion(q) {
+  const s = String(q || '').trim();
+  if (!s) return '(buyer did not provide a question body)';
+  if (s.length <= MAX_ANSWER_PROMPT_CHARS) return s;
+  return s.slice(0, MAX_ANSWER_PROMPT_CHARS - 40) + '\n...[TRUNCATED]...';
+}
+
+function _answerFilePath(taskId) {
+  const safe = String(taskId || 'task').replace(/[^a-zA-Z0-9_\-]/g, '_').slice(0, 64);
+  return path.join(getMemoryDir(), 'atp_answer_' + safe + '.md');
+}
+
+function _buildSpawnTask(task, opts) {
+  const capabilities = Array.isArray(task.capabilities) ? task.capabilities.slice(0, 8) : [];
+  const signalsCsv = task.signals ? String(task.signals) : '';
+  const answerPath = _answerFilePath(task.id);
+  const question = _clipQuestion(task.user_question_body || task.description || task.title);
+
+  const evolverExec = opts && opts.evolverExec ? opts.evolverExec : 'node index.js';
+
+  const lines = [
+    'You are an ATP merchant sub-agent. A buyer has paid credits for your node to answer their request.',
+    '',
+    '# Task',
+    '- Task ID: ' + task.id,
+    '- ATP Order ID: ' + task.atp_order_id,
+    '- Title: ' + String(task.title || '(no title)').slice(0, 200),
+    '- Capabilities requested: ' + (capabilities.length ? capabilities.join(', ') : '(none)'),
+    '- Signals: ' + (signalsCsv || '(none)'),
+    '',
+    '# Buyer question',
+    question,
+    '',
+    '# Your job',
+    '1. Produce a concrete, useful answer to the buyer question above.',
+    '   - Use your existing tools (web search, code read, reasoning) as appropriate.',
+    '   - Keep the answer focused and actionable; do not invent facts.',
+    '   - If the question is ambiguous, answer the most reasonable interpretation and state your assumption.',
+    '2. Write the full answer to this file (plain text or markdown):',
+    '     ' + answerPath,
+    '3. Settle the order by running EXACTLY this command from the Evolver install dir:',
+    '     ' + evolverExec + ' atp-complete \\',
+    '       --task-id=' + task.id + ' \\',
+    '       --order-id=' + task.atp_order_id + ' \\',
+    '       --answer-file=' + answerPath +
+      (capabilities.length ? ' \\\n       --capabilities=' + capabilities.join(',') : '') +
+      (signalsCsv ? ' \\\n       --signals=' + signalsCsv : ''),
+    '4. If atp-complete prints "[ATP-Complete] OK asset_id=...", you are done.',
+    '   If it prints "FAILED", read the stage= field. Safe to retry the same command.',
+    '',
+    '# Hard rules',
+    '- Do NOT commit or push any repo changes -- this is a per-order side task, not a code evolution.',
+    '- Do NOT run `node index.js solidify` or `node index.js run`.',
+    '- Do NOT fabricate the answer; if you cannot answer, still run atp-complete with a short',
+    '  honest explanation so the buyer is not left waiting for 7 days.',
+    '- Keep the answer under 12k characters.',
+  ];
+  return lines.join('\n');
+}
+
+/**
+ * Fetch a pickup action if one is due. Idempotent -- safe to call from the
+ * main loop every cycle.
+ *
+ * @param {object} [opts]
+ * @param {number} [opts.limit=5] -- how many Hub tasks to consider per call
+ * @param {string} [opts.evolverExec] -- how the wrapper should invoke Evolver
+ * @returns {Promise<null | { spawnCall: string, task: object }>}
+ *   null when there is nothing to do; otherwise a sessions_spawn() string
+ *   the caller SHOULD print to stdout on its next cycle output and the task
+ *   we picked so the caller can log it.
+ */
+async function pickOne(opts) {
+  if (!_isEnabled()) return null;
+  const limit = Math.max(1, Math.min(20, Number(opts && opts.limit) || 5));
+
+  let listResult;
+  try {
+    listResult = await hubClient.listMyTasks(limit);
+  } catch (_) {
+    return null;
+  }
+  if (!listResult || !listResult.ok) return null;
+
+  const tasks = (listResult.data && Array.isArray(listResult.data.tasks))
+    ? listResult.data.tasks
+    : (Array.isArray(listResult.data) ? listResult.data : []);
+  if (!tasks.length) return null;
+
+  const ledger = _readLedger();
+  let picked = null;
+  for (const t of tasks) {
+    if (!_isEligible(t)) continue;
+    if (_recentlySpawned(ledger, t.id)) continue;
+    picked = t;
+    break;
+  }
+  if (!picked) return null;
+
+  const spawnTask = _buildSpawnTask(picked, opts);
+  const spawnCall = renderSessionsSpawnCall({
+    task: spawnTask,
+    agentId: 'atp_pickup',
+    cleanup: 'delete',
+    label: 'atp_pickup_' + String(picked.id).slice(0, 32),
+  });
+
+  ledger.spawned = ledger.spawned || {};
+  ledger.spawned[picked.id] = { at: Date.now(), order_id: picked.atp_order_id };
+  _writeLedger(ledger);
+
+  return { spawnCall, task: picked };
+}
+
+/**
+ * Forget a previously-spawned task so the main loop will retry it next cycle.
+ * Called by callers that detected the spawn channel was unavailable (e.g.
+ * wrapper not attached) so we do not burn the cooldown on a no-op spawn.
+ */
+function forget(taskId) {
+  if (!taskId) return;
+  const ledger = _readLedger();
+  if (ledger.spawned && ledger.spawned[taskId]) {
+    delete ledger.spawned[taskId];
+    _writeLedger(ledger);
+  }
+}
+
+module.exports = {
+  pickOne,
+  forget,
+  _isEnabled,
+  _isEligible,
+  _buildSpawnTask,
+  _recentlySpawned,
+  _answerFilePath,
+};

package/src/atp/index.js

@@ -9,6 +9,8 @@
 //   defaultHandler  - default order handler + config helpers for auto-ATP
 //   autoBuyer       - opt-out capability-gap auto order helper with budget caps
 //   autoDeliver     - opt-out merchant-side submitDelivery daemon
+//   atpTaskPickup   - merchant-side bridge from pre-claimed ATP tasks to sessions_spawn
+//   atpExecute      - end-to-end completer (publish Gene+Capsule, complete, deliver)
 //   cli             - parsers and runners for the `buy`/`orders`/`verify` subcommands
 
 const hubClient = require('./hubClient');
@@ -18,6 +20,8 @@ const serviceHelper = require('./serviceHelper');
 const defaultHandler = require('./defaultHandler');
 const autoBuyer = require('./autoBuyer');
 const autoDeliver = require('./autoDeliver');
+const atpTaskPickup = require('./atpTaskPickup');
+const atpExecute = require('./atpExecute');
 const cli = require('./cli');
 
 module.exports = {
@@ -28,5 +32,7 @@ module.exports = {
   defaultHandler,
   autoBuyer,
   autoDeliver,
+  atpTaskPickup,
+  atpExecute,
   cli,
 };