feat(a2a): orchestrator + JSONL run logs

a2a_orchestrate sequences verify_safe -> inventory -> secure_sweep(dry) ->
lp_unwind(dry) -> prep_eis_deploy, emitting one JSONL line per step and aborting
on the first failure. No flag combination broadcasts.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: BotID Developer

scripts/a2a_orchestrate.cjs

@@ -0,0 +1,114 @@
+#!/usr/bin/env node
+/**
+ * C1 — a2a_orchestrate: single entry point running every READ-ONLY / DRY-RUN
+ * step in dependency order. No flag combination here can broadcast — each
+ * broadcast remains a separate, manually-gated, owner-run command.
+ *
+ * Order: verify_safe -> inventory -> secure_sweep(dry) -> lp_unwind(dry) -> prep_eis_deploy
+ * Output: one JSONL line per step to out/a2a_run_<ISO_TS>.jsonl, final a2a_summary line.
+ * On any non-OK step: abort the rest, still emit the summary with the failure reason.
+ *
+ * Env: SAFE_ADDRESS (required), FROM_ADDRESS (default 0x9545…6956),
+ *      POOL_ADDRESS (for lp_unwind), DEPLOYER_ADDRESS (for prep_eis_deploy), RPC.
+ */
+const fs = require('node:fs');
+const path = require('node:path');
+const { execFileSync } = require('node:child_process');
+
+const ts = () => new Date().toISOString();
+const FROM = process.env.FROM_ADDRESS || '0x9545e2439c5c75d3aA723AcaC1AA6B0fa1DB6956';
+const SAFE = process.env.SAFE_ADDRESS || '';
+
+const runDir = path.join(process.cwd(), 'out');
+fs.mkdirSync(runDir, { recursive: true });
+fs.mkdirSync(path.join(process.cwd(), '.yennefer-cache'), { recursive: true });
+const runFile = path.join(runDir, `a2a_run_${ts().replace(/[:.]/g, '-')}.jsonl`);
+const append = (obj) => fs.appendFileSync(runFile, JSON.stringify(obj) + '\n');
+
+function lastJsonLine(text) {
+  const lines = String(text || '').trim().split('\n').filter(Boolean);
+  for (let i = lines.length - 1; i >= 0; i--) {
+    try { return JSON.parse(lines[i]); } catch { /* not json */ }
+  }
+  return null;
+}
+
+// Run a child step; returns {ok, line}. Never throws.
+function runStep(name, file, args, extraEnv, cacheTo) {
+  const env = { ...process.env, ...extraEnv };
+  let stdout = '', ok = false;
+  try {
+    stdout = execFileSync('node', [file, ...args], { env, encoding: 'utf8', stdio: ['ignore', 'pipe', 'inherit'] });
+    ok = true;
+  } catch (e) {
+    stdout = (e.stdout || '').toString();
+    ok = false;
+  }
+  if (cacheTo) {
+    try { fs.writeFileSync(cacheTo, JSON.stringify({ step: name, raw: stdout, ts: ts() }, null, 2)); } catch { /* ignore */ }
+  }
+  const emitted = lastJsonLine(stdout);
+  const line = emitted && emitted.step
+    ? { ...emitted, ok: emitted.ok !== undefined ? emitted.ok : ok }
+    : { step: name, ok, ts: ts() };
+  append(line);
+  return { ok: line.ok === true, line };
+}
+
+function summarize(steps, ok, nextActions, failReason) {
+  const summary = {
+    step: 'a2a_summary', ok, ts: ts(),
+    run_file: path.relative(process.cwd(), runFile),
+    steps: steps.map((s) => ({ step: s.line.step, ok: s.ok })),
+    next_actions: nextActions,
+    ...(failReason ? { fail_reason: failReason } : {}),
+  };
+  append(summary);
+  process.stdout.write(JSON.stringify(summary) + '\n');
+  process.exit(ok ? 0 : 1);
+}
+
+function main() {
+  if (!SAFE || !/^0x[0-9a-fA-F]{40}$/.test(SAFE)) {
+    append({ step: 'a2a_preflight', ok: false, ts: ts(), reason: 'SAFE_ADDRESS unset/malformed' });
+    return summarize([], false, ['Deploy the Safe (docs/safe-setup.md), then export SAFE_ADDRESS'], 'SAFE_ADDRESS unset');
+  }
+
+  const cacheDir = path.join(process.cwd(), '.yennefer-cache');
+  const steps = [];
+
+  // 1. verify_safe — gate for everything downstream.
+  const vs = runStep('verify_safe', 'scripts/verify_safe.cjs', [], { SAFE_ADDRESS: SAFE });
+  steps.push(vs);
+  if (!vs.ok) {
+    return summarize(steps, false,
+      ['Safe failed verification — confirm it is deployed on Base (chainId 8453), 2-of-3, via docs/safe-setup.md, then re-run'],
+      'verify_safe failed');
+  }
+
+  // 2. inventory (read-only) — source wallet holdings.
+  steps.push(runStep('inventory', 'scripts/inventory.cjs', [FROM], {}, path.join(cacheDir, 'inventory.json')));
+
+  // 3. secure_sweep dry-run -> Safe.
+  steps.push(runStep('secure_sweep', 'scripts/secure_sweep.cjs', ['--to', SAFE, '--from', FROM], {}));
+
+  // 4. lp_unwind dry-run -> Safe.
+  steps.push(runStep('lp_unwind', 'scripts/lp_unwind.cjs', [], { SAFE_ADDRESS: SAFE, TO_ADDRESS: SAFE, FROM_ADDRESS: FROM }));
+
+  // 5. prep_eis_deploy (treasurySink = Safe).
+  steps.push(runStep('prep_eis_deploy', 'scripts/prep_eis_deploy.cjs', [], { SAFE_ADDRESS: SAFE }));
+
+  const allOk = steps.every((s) => s.ok);
+  const nextActions = [];
+  if (!steps.find((s) => s.line.step === 'lp_unwind')?.ok) {
+    nextActions.push('Set POOL_ADDRESS to the real Aerodrome LP token (not the router) and re-run lp_unwind');
+  }
+  if (!steps.find((s) => s.line.step === 'prep_eis_deploy')?.ok) {
+    nextActions.push('Add+compile EulersIdentitySynthesis (git apply patches/eis-immutable-sink.patch; npx hardhat compile), set DEPLOYER_ADDRESS');
+  }
+  nextActions.push('Review out/*.json plans; run each broadcast manually with your Ledger + the per-script gate');
+
+  summarize(steps, allOk, nextActions, allOk ? null : 'one or more dry-run steps reported not-ok');
+}
+
+main();

scripts/inventory.cjs

@@ -0,0 +1,65 @@
+#!/usr/bin/env node
+/**
+ * READ-ONLY asset inventory for a Base address.
+ * No private key, no signing, no transactions. Safe to run anytime.
+ *
+ * Usage:
+ *   node scripts/inventory.cjs 0xWALLET [0xWALLET2 ...]
+ *   BASE_RPC_URL=https://... node scripts/inventory.cjs 0xWALLET
+ */
+const { ethers } = require('ethers');
+
+const RPC = process.env.BASE_MAINNET_RPC || process.env.BASE_RPC_URL || 'https://mainnet.base.org';
+
+// Known Base tokens/positions to probe. Extend freely.
+const TOKENS = [
+  { sym: 'QFLOP', addr: '0xa8F5e136aa74803B8DB377a14f79F6c8Dd3959c7' },
+  { sym: 'wQFLOP', addr: '0x69262A2D7c92c074729823B654fE7E4Cdb749747' },
+  { sym: 'WETH', addr: '0x4200000000000000000000000000000000000006' },
+  { sym: 'AERO-LP(wQFLOP/WETH)', addr: '0x4aBC6D796cd036b6f1E433A97F9784a00f90C53e' },
+];
+
+const ERC20_ABI = [
+  'function balanceOf(address) view returns (uint256)',
+  'function decimals() view returns (uint8)',
+  'function symbol() view returns (string)',
+];
+
+async function inventory(provider, address) {
+  console.log(`\n=== ${address} ===`);
+  const eth = await provider.getBalance(address);
+  console.log(`  ETH: ${ethers.formatEther(eth)}`);
+
+  for (const t of TOKENS) {
+    try {
+      const c = new ethers.Contract(t.addr, ERC20_ABI, provider);
+      const [bal, dec] = await Promise.all([c.balanceOf(address), c.decimals().catch(() => 18)]);
+      const human = ethers.formatUnits(bal, dec);
+      const flag = bal > 0n ? '  <-- nonzero' : '';
+      console.log(`  ${t.sym} (${t.addr}): ${human}${flag}`);
+    } catch (e) {
+      console.log(`  ${t.sym} (${t.addr}): <read error: ${e.shortMessage || e.message}>`);
+    }
+  }
+}
+
+async function main() {
+  const targets = process.argv.slice(2);
+  if (targets.length === 0) {
+    console.error('usage: node scripts/inventory.cjs 0xWALLET [0xWALLET2 ...]');
+    process.exit(2);
+  }
+  const provider = new ethers.JsonRpcProvider(RPC);
+  const net = await provider.getNetwork();
+  console.log(`RPC: ${RPC}  chainId: ${net.chainId}`);
+  for (const addr of targets) {
+    if (!/^0x[0-9a-fA-F]{40}$/.test(addr)) {
+      console.log(`\n=== ${addr} ===\n  SKIP: not a valid address`);
+      continue;
+    }
+    await inventory(provider, ethers.getAddress(addr));
+  }
+  console.log('\n(read-only — no transactions sent)');
+}
+
+main().catch((e) => { console.error(e); process.exit(1); });

scripts/secure_sweep.cjs

@@ -0,0 +1,155 @@
+#!/usr/bin/env node
+/**
+ * secure_sweep — evacuate assets from a (possibly compromised) hot wallet to a
+ * secure destination (your Ledger / Safe), as part of key rotation.
+ *
+ * SAFETY MODEL:
+ *   - DRY-RUN by default: builds + simulates + prints. Sends NOTHING.
+ *   - Broadcasting is DOUBLE-GATED and must be run BY YOU:
+ *       --broadcast  AND  env I_UNDERSTAND_IRREVERSIBLE=yes
+ *   - The hot key is read from YOUR env (ETH_PRIVATE_KEY) at run time. This
+ *     script (and Claude) never store, log, or transmit it anywhere.
+ *   - Transfers are irreversible. Review the dry-run plan before broadcasting.
+ *
+ * Usage (dry-run, no key needed):
+ *   node scripts/secure_sweep.cjs --to 0xLEDGER --from 0xHOTWALLET
+ *
+ * Usage (broadcast — YOU run this, with your key in env):
+ *   ETH_PRIVATE_KEY=0x... I_UNDERSTAND_IRREVERSIBLE=yes \
+ *   node scripts/secure_sweep.cjs --to 0xLEDGER --broadcast
+ *
+ * Note: ERC-20 transfers cost gas — the hot wallet needs enough ETH first.
+ *       LP positions (Aerodrome) must be withdrawn via the router separately;
+ *       this script handles native ETH + ERC-20 balances only.
+ */
+const { ethers } = require('ethers');
+
+const RPC = process.env.BASE_MAINNET_RPC || process.env.BASE_RPC_URL || 'https://mainnet.base.org';
+
+const DEFAULT_TOKENS = {
+  QFLOP: '0xa8F5e136aa74803B8DB377a14f79F6c8Dd3959c7',
+  wQFLOP: '0x69262A2D7c92c074729823B654fE7E4Cdb749747',
+  WETH: '0x4200000000000000000000000000000000000006',
+};
+
+const ERC20_ABI = [
+  'function balanceOf(address) view returns (uint256)',
+  'function decimals() view returns (uint8)',
+  'function transfer(address to, uint256 amount) returns (bool)',
+];
+
+function parseArgs(argv) {
+  const a = { broadcast: false, to: null, from: null, tokens: Object.values(DEFAULT_TOKENS) };
+  for (let i = 0; i < argv.length; i++) {
+    if (argv[i] === '--broadcast') a.broadcast = true;
+    else if (argv[i] === '--to') a.to = argv[++i];
+    else if (argv[i] === '--from') a.from = argv[++i];
+    else if (argv[i] === '--tokens') a.tokens = argv[++i].split(',').map((s) => s.trim());
+  }
+  return a;
+}
+
+async function main() {
+  const args = parseArgs(process.argv.slice(2));
+  const provider = new ethers.JsonRpcProvider(RPC);
+
+  if (!args.to || !/^0x[0-9a-fA-F]{40}$/.test(args.to)) {
+    console.error('ERROR: --to <destination address> is required (your Ledger/Safe).');
+    process.exit(2);
+  }
+  const dest = ethers.getAddress(args.to);
+
+  // Resolve the source. Broadcast derives it from the key; dry-run can use --from.
+  let signer = null;
+  let from;
+  const rawKey = process.env.ETH_PRIVATE_KEY || process.env.BASE_PRIVATE_KEY || '';
+  if (/^0x[0-9a-fA-F]{64}$/.test(rawKey)) {
+    signer = new ethers.Wallet(rawKey, provider);
+    from = await signer.getAddress();
+  } else if (args.from && /^0x[0-9a-fA-F]{40}$/.test(args.from)) {
+    from = ethers.getAddress(args.from);
+  } else {
+    console.error('ERROR: provide --from <addr> for dry-run, or set ETH_PRIVATE_KEY to broadcast.');
+    process.exit(2);
+  }
+
+  const net = await provider.getNetwork();
+  console.log(`RPC ${RPC} chainId ${net.chainId}`);
+  console.log(`FROM ${from}`);
+  console.log(`TO   ${dest}`);
+  console.log(`MODE ${args.broadcast ? 'BROADCAST' : 'DRY-RUN'}\n`);
+
+  if (from.toLowerCase() === dest.toLowerCase()) {
+    console.error('ERROR: source and destination are identical. Aborting.');
+    process.exit(2);
+  }
+
+  const feeData = await provider.getFeeData();
+  const gasPrice = feeData.maxFeePerGas || feeData.gasPrice || 0n;
+  const plan = [];
+
+  // ERC-20 balances first (these need gas to move).
+  for (const addr of args.tokens) {
+    if (!/^0x[0-9a-fA-F]{40}$/.test(addr)) continue;
+    try {
+      const c = new ethers.Contract(addr, ERC20_ABI, provider);
+      const [bal, dec] = await Promise.all([c.balanceOf(from), c.decimals().catch(() => 18)]);
+      if (bal > 0n) {
+        let gas = 65000n;
+        try { gas = await c.transfer.estimateGas(dest, bal, { from }); } catch { /* keep default */ }
+        plan.push({ kind: 'ERC20', token: addr, amount: bal.toString(), human: ethers.formatUnits(bal, dec), gas });
+      }
+    } catch (e) {
+      console.log(`  (skip ${addr}: ${e.shortMessage || e.message})`);
+    }
+  }
+
+  // Native ETH last — sweep balance minus a gas reserve for the ERC-20 txs above.
+  const ethBal = await provider.getBalance(from);
+  const erc20GasCost = plan.reduce((s, p) => s + (p.gas || 0n), 0n) * gasPrice;
+  const ethTransferGas = 21000n;
+  const reserve = erc20GasCost + ethTransferGas * gasPrice;
+  const ethToSend = ethBal > reserve ? ethBal - reserve : 0n;
+
+  console.log('PLANNED TRANSFERS:');
+  for (const p of plan) console.log(`  ERC20 ${p.human}  (${p.token})  ~gas ${p.gas}`);
+  console.log(`  ETH   ${ethers.formatEther(ethToSend)} (after gas reserve ${ethers.formatEther(reserve)})`);
+
+  // Sufficiency check — the classic trap: tokens present, no gas to move them.
+  if (plan.length > 0 && ethBal < erc20GasCost) {
+    console.log(`\n⚠️  INSUFFICIENT GAS: holding ${plan.length} token balance(s) but only ` +
+      `${ethers.formatEther(ethBal)} ETH; need ~${ethers.formatEther(erc20GasCost)} ETH to move them. ` +
+      `Fund ${from} with a little ETH first.`);
+  }
+
+  if (!args.broadcast) {
+    console.log('\nDRY-RUN complete. Nothing sent. Re-run with --broadcast (and the safety env) to execute.');
+    return;
+  }
+
+  // ── BROADCAST PATH (gated; intended to be run by the asset owner only) ──
+  if (process.env.I_UNDERSTAND_IRREVERSIBLE !== 'yes') {
+    console.error('\nREFUSED: --broadcast requires env I_UNDERSTAND_IRREVERSIBLE=yes. ' +
+      'These transfers are irreversible. Aborting.');
+    process.exit(1);
+  }
+  if (!signer) {
+    console.error('REFUSED: no signing key in env. Set ETH_PRIVATE_KEY to broadcast.');
+    process.exit(1);
+  }
+
+  for (const p of plan) {
+    const c = new ethers.Contract(p.token, ERC20_ABI, signer);
+    const tx = await c.transfer(dest, BigInt(p.amount));
+    console.log(`  sent ERC20 ${p.human} (${p.token}) tx ${tx.hash}`);
+    await tx.wait();
+  }
+  if (ethToSend > 0n) {
+    const tx = await signer.sendTransaction({ to: dest, value: ethToSend });
+    console.log(`  sent ETH ${ethers.formatEther(ethToSend)} tx ${tx.hash}`);
+    await tx.wait();
+  }
+  console.log('\nSweep complete. Verify on BaseScan, then retire the old key.');
+}
+
+main().catch((e) => { console.error(e); process.exit(1); });