@thirdfy/agent-cli 0.1.48 → 0.2.1

package/src/runtime/execution/runners.mjs

@@ -0,0 +1,702 @@
+import { randomUUID } from 'crypto';
+import { requireFlag } from '../../core/args.mjs';
+import { createCliError } from '../../core/envelope.mjs';
+import {
+  normalizeRunMode,
+  normalizeManagedRunMode,
+  normalizeHybridWalletMode,
+  normalizeEffectCheckMode,
+  getEffectiveRunMode,
+  parseBooleanFlag,
+} from '../../core/runMode.mjs';
+import { apiGet, apiPost } from '../../core/http.mjs';
+import { createRequire } from 'module';
+
+const require = createRequire(import.meta.url);
+const { normalizeIntentResponse } = require('../../utils/cli/intentNormalization.cjs');
+
+export function createExecutionRunners(deps) {
+  const {
+    buildIntentPayload,
+    buildBuildTxPayload,
+    buildManagedExecutePayload,
+    getPreparedParams,
+    resolveEffectiveUserDid,
+    resolveTokenInForFunding,
+    shouldUseBuildTxPreflight,
+    shouldUseBuildTxExecution,
+    buildBitfinexOnboardingCommand,
+    inferBitfinexPermissionProfileFromAction,
+    resolveAgentApiKey,
+    loadEthers,
+    signAndBroadcastWithOws,
+    readEffectBalances,
+    resolveUnsignedTx,
+    sleepMs,
+  } = deps;
+
+function applyExecutionFallbackHints(normalized, { flags, runMode, resolvedAction }) {
+  if (!normalized || typeof normalized !== 'object') return normalized;
+  const next = { ...normalized };
+  const reasons = new Set();
+  const topBlockedReason = String(next.blockedReason || '').trim();
+  if (topBlockedReason) reasons.add(topBlockedReason);
+  const blockedByReason = next.blockedByReason && typeof next.blockedByReason === 'object' ? next.blockedByReason : {};
+  for (const key of Object.keys(blockedByReason)) {
+    if (String(key || '').trim()) reasons.add(String(key).trim());
+  }
+  const resolvedActionLower = String(resolvedAction || '').trim().toLowerCase();
+  const looksBitfinexAction = resolvedActionLower.includes('bitfinex');
+  const permissionProfile = inferBitfinexPermissionProfileFromAction(resolvedActionLower);
+  const cexCredentialMissingSignals = new Set([
+    'CEX_CREDENTIAL_NOT_FOUND',
+    'BITFINEX_CREDENTIALS_NOT_IN_CONTEXT',
+    'BITFINEX_CREDENTIALS_NOT_IN_THIRDFY_DELEGATION_CONTEXT',
+    'BITFINEX_ENV_CREDENTIALS_NOT_CONFIGURED',
+  ]);
+  const hasMissingCredentialSignal = Array.from(reasons).some((code) => cexCredentialMissingSignals.has(code));
+  if (looksBitfinexAction && hasMissingCredentialSignal) {
+    next.onboardingHint = {
+      type: 'bitfinex_credentials',
+      message:
+        'Bitfinex credentials are missing for this delegated account. Onboard credentials first, then retry the same command.',
+      command: buildBitfinexOnboardingCommand(permissionProfile),
+    };
+  }
+  if (
+    looksBitfinexAction &&
+    runMode !== 'thirdfy' &&
+    runMode !== 'agent_wallet' &&
+    (topBlockedReason === 'SELF_MODE_REQUIRES_BUILD_TX' || topBlockedReason === 'HYBRID_MODE_REQUIRES_BUILD_TX')
+  ) {
+    next.onboardingHint = {
+      ...(next.onboardingHint || {}),
+      runMode: 'thirdfy',
+      runModeMessage: 'Bitfinex actions require delegated execute-intent rail. Re-run with --run-mode thirdfy.',
+    };
+  }
+  return next;
+}
+
+async function runPreflightByMode(runMode, ctx, flags, resolved, options = {}) {
+  const resolvedAction = resolved.resolvedAction;
+  if (runMode === 'agent_wallet') {
+    const preflight = await resolveManagedExecutionPreflight(ctx, flags, resolved, {
+      runMode,
+      requireFundingCheck: true,
+      preflightSeed: options.managedPreflight,
+    });
+    const normalized = normalizeIntentResponse({
+      success: preflight.success,
+      status: preflight.success ? 'ready' : 'failed',
+      mode: 'agent_wallet',
+      executionWalletAddress: preflight.executionWalletAddress || null,
+      signerMethod: preflight.signerMethod || 'managed_wallet_server',
+      blockedReason: preflight.blockedReason || null,
+      blockedStage: preflight.blockedStage || null,
+      error: preflight.success ? null : preflight.error || 'Managed wallet preflight failed',
+      preflightBlocked: !preflight.success,
+      fundingTokenBalance: preflight.fundingTokenBalance || null,
+      executionWalletPreflight: preflight,
+    });
+    normalized.executionWalletAddress = preflight.executionWalletAddress || null;
+    normalized.signerMethod = preflight.signerMethod || 'managed_wallet_server';
+    normalized.executionWalletPreflight = preflight;
+    normalized.fundingTokenBalance = preflight.fundingTokenBalance || null;
+    return {
+      message: preflight.success ? 'Managed wallet preflight completed' : 'Managed wallet preflight failed',
+      route: 'execution_wallet_preflight',
+      normalized,
+    };
+  }
+  if (runMode === 'self') {
+    const route = shouldUseBuildTxPreflight(runMode, resolved) ? 'build_tx' : 'execute_intent_validation';
+    const normalized = await executeSelfRun(
+      ctx,
+      flags,
+      resolved,
+      { skipPreflight: route === 'build_tx' }
+    );
+    const blockedByGovernance = !normalized.success && Boolean(normalized.preflightBlocked);
+    return {
+      message: blockedByGovernance
+        ? 'Self preflight blocked by governance'
+        : normalized.success
+          ? 'Self preflight completed (unsigned transaction ready)'
+          : 'Self preflight failed',
+      route,
+      normalized,
+    };
+  }
+  if (runMode === 'hybrid' && options.hybridWalletMode === 'agent_wallet') {
+    const managedPayload = buildIntentPayload(flags, {
+      validationOnly: true,
+      forceIdempotency: false,
+      resolvedAction,
+      runMode: 'agent_wallet',
+      mirrorOnly: false,
+      hybridWalletMode: 'agent_wallet',
+    });
+    const managedResponse = await apiPost(ctx, '/api/v1/agent/execute-intent', managedPayload);
+    const managedNormalized = normalizeIntentResponse(managedResponse);
+    const mirrorPayload = buildIntentPayload(flags, {
+      validationOnly: true,
+      forceIdempotency: false,
+      resolvedAction,
+      runMode: 'hybrid',
+      mirrorOnly: true,
+      hybridWalletMode: 'agent_wallet',
+    });
+    const mirrorResponse = await apiPost(ctx, '/api/v1/agent/execute-intent', mirrorPayload);
+    const mirrorNormalized = normalizeIntentResponse(mirrorResponse);
+    return {
+      message:
+        managedNormalized.success && mirrorNormalized.success
+          ? 'Hybrid preflight completed (agent_wallet + thirdfy mirror)'
+          : 'Hybrid preflight failed (agent_wallet + thirdfy mirror)',
+      route: 'execute_intent_validation_dual',
+      normalized: normalizeIntentResponse({
+        success: Boolean(managedNormalized.success && mirrorNormalized.success),
+        status: mirrorNormalized.status || managedNormalized.status || 'failed',
+        mode: 'hybrid',
+        hybridWalletMode: 'agent_wallet',
+        managed: managedNormalized,
+        mirror: mirrorNormalized,
+        error: managedNormalized.error || mirrorNormalized.error || null,
+      }),
+    };
+  }
+  const payload = buildIntentPayload(flags, {
+    validationOnly: true,
+    forceIdempotency: false,
+    resolvedAction,
+    runMode,
+    mirrorOnly: runMode === 'hybrid',
+  });
+  const response = await apiPost(ctx, '/api/v1/agent/execute-intent', payload);
+  const normalized = normalizeIntentResponse(response);
+  return {
+    message: normalized.success
+      ? runMode === 'hybrid'
+        ? 'Hybrid mirror preflight completed'
+        : 'Preflight completed'
+      : runMode === 'hybrid'
+        ? 'Hybrid mirror preflight failed'
+        : 'Preflight failed',
+    route: 'execute_intent_validation',
+    normalized,
+  };
+}
+
+async function runExecutionByMode(runMode, ctx, flags, resolved, options) {
+  if (runMode === 'thirdfy') {
+    const normalized = await executeThirdfyRun(ctx, flags, resolved, options, runMode);
+    const preflightBlocked = !normalized.success && Boolean(normalized.preflightBlocked);
+    return {
+      code: normalized.success ? 'RUN_QUEUED' : preflightBlocked ? 'PREFLIGHT_BLOCKED' : 'RUN_FAILED',
+      message: normalized.success
+        ? 'Execution intent queued'
+        : preflightBlocked
+          ? 'Preflight blocked execution'
+          : 'Execution failed',
+      idempotencyKey: normalized.idempotencyKey || null,
+      normalized,
+    };
+  }
+  if (runMode === 'agent_wallet') {
+    const normalized = await executeManagedWalletRun(ctx, flags, resolved, options);
+    const preflightBlocked = !normalized.success && Boolean(normalized.preflightBlocked);
+    return {
+      code: normalized.success ? 'WALLET_EXECUTED' : preflightBlocked ? 'PREFLIGHT_BLOCKED' : 'RUN_FAILED',
+      message: normalized.success
+        ? 'Managed wallet execution completed'
+        : preflightBlocked
+          ? 'Managed wallet preflight blocked execution'
+          : 'Managed wallet execution failed',
+      idempotencyKey: normalized.idempotencyKey || null,
+      normalized,
+    };
+  }
+  if (runMode === 'self') {
+    const normalized = await executeSelfRun(ctx, flags, resolved, options);
+    const preflightBlocked = !normalized.success && Boolean(normalized.preflightBlocked);
+    return {
+      code: normalized.success
+        ? 'SELF_UNSIGNED_TX_READY'
+        : preflightBlocked
+          ? 'PREFLIGHT_BLOCKED'
+          : 'SELF_EXECUTION_FAILED',
+      message: normalized.success
+        ? 'Unsigned transaction prepared for self-custody execution'
+        : preflightBlocked
+          ? 'Preflight blocked self execution'
+          : 'Self-custody execution failed',
+      idempotencyKey: null,
+      normalized,
+    };
+  }
+  const normalized = await executeHybridRun(ctx, flags, resolved, options);
+  const preflightBlocked = !normalized.success && Boolean(normalized.preflightBlocked);
+  const hybridWalletMode = normalizeHybridWalletMode(
+    normalized.hybridWalletMode || options?.hybridWalletMode || flags.hybridWalletMode || 'self',
+  );
+  return {
+    code: normalized.success ? 'HYBRID_READY' : preflightBlocked ? 'PREFLIGHT_BLOCKED' : 'HYBRID_FAILED',
+    message: normalized.success
+      ? hybridWalletMode === 'agent_wallet'
+        ? 'Hybrid execution prepared (agent wallet + mirror preflight)'
+        : 'Hybrid execution prepared (self tx + mirror preflight)'
+      : preflightBlocked
+        ? 'Preflight blocked hybrid execution'
+        : 'Hybrid execution failed',
+    idempotencyKey: normalized.idempotencyKey || null,
+    normalized,
+  };
+}
+
+async function executeThirdfyRun(ctx, flags, resolved, options, runMode = 'thirdfy') {
+  const skipPreflight = Boolean(options?.skipPreflight);
+  if (!skipPreflight) {
+    const preflightPayload = buildIntentPayload(flags, {
+      validationOnly: true,
+      forceIdempotency: false,
+      resolvedAction: resolved.resolvedAction,
+      runMode,
+      mirrorOnly: false,
+      hybridWalletMode: options?.hybridWalletMode,
+    });
+    const preflight = await apiPost(ctx, '/api/v1/agent/execute-intent', preflightPayload);
+    const preflightNormalized = normalizeIntentResponse(preflight);
+    const blockedCount = preflightNormalized.blocked || 0;
+    if (!preflightNormalized.success || blockedCount > 0) {
+      preflightNormalized.success = false;
+      preflightNormalized.error = preflightNormalized.error || 'Preflight blocked execution';
+      preflightNormalized.preflightBlocked = true;
+      return preflightNormalized;
+    }
+  }
+  const payload = buildIntentPayload(flags, {
+    validationOnly: false,
+    forceIdempotency: true,
+    resolvedAction: resolved.resolvedAction,
+    runMode,
+    mirrorOnly: false,
+    hybridWalletMode: options?.hybridWalletMode,
+  });
+  const response = await apiPost(ctx, '/api/v1/agent/execute-intent', payload);
+  const normalized = normalizeIntentResponse(response);
+  normalized.idempotencyKey = payload.idempotencyKey;
+  return normalized;
+}
+
+async function executeManagedWalletRun(ctx, flags, resolved, options) {
+  const skipPreflight = Boolean(options?.skipPreflight);
+  let preflight = null;
+  if (!skipPreflight) {
+    preflight = await resolveManagedExecutionPreflight(ctx, flags, resolved, {
+      runMode: 'agent_wallet',
+      requireFundingCheck: true,
+      preflightSeed: options?.managedPreflight,
+    });
+    if (!preflight.success) {
+      const normalized = normalizeIntentResponse({
+        success: false,
+        status: 'failed',
+        mode: 'agent_wallet',
+        blockedReason: preflight.blockedReason || 'PRECHECK_FAILED',
+        blockedStage: preflight.blockedStage || 'routing',
+        error: preflight.error || 'Managed wallet preflight failed',
+        preflightBlocked: true,
+        executionWalletAddress: preflight.executionWalletAddress || null,
+        executionWalletPreflight: preflight,
+      });
+      normalized.executionWalletAddress = preflight.executionWalletAddress || null;
+      normalized.executionWalletPreflight = preflight;
+      return normalized;
+    }
+  }
+  const payload = buildManagedExecutePayload(flags, {
+    resolvedAction: resolved.resolvedAction,
+    runMode: 'agent_wallet',
+    forceIdempotency: true,
+  });
+  const response = await apiPost(ctx, '/api/v1/agent/execute', payload);
+  const normalized = normalizeIntentResponse({
+    success: Boolean(response?.success),
+    status: response?.success ? 'completed' : 'failed',
+    mode: 'agent_wallet',
+    txHash: response?.txHash || null,
+    blockedReason: response?.blockedReason || response?.data?.blockedReason || null,
+    blockedStage: response?.blockedStage || response?.data?.blockedStage || null,
+    error: response?.error || null,
+    executionWalletAddress: response?.executionWalletAddress || response?.data?.executionWalletAddress || null,
+    signerMethod: 'managed_wallet_server',
+    idempotencyKey: payload.executionIdempotencyKey || null,
+    executionWalletPreflight: preflight,
+    amountNormalization: response?.amountNormalization || response?.data?.amountNormalization || null,
+    raw: response,
+  });
+  normalized.executionWalletAddress = response?.executionWalletAddress || response?.data?.executionWalletAddress || null;
+  normalized.signerMethod = 'managed_wallet_server';
+  normalized.executionWalletPreflight = preflight;
+  normalized.amountNormalization = response?.amountNormalization || response?.data?.amountNormalization || null;
+  normalized.raw = response;
+  normalized.idempotencyKey = payload.executionIdempotencyKey || null;
+  return normalized;
+}
+
+async function executeSelfRun(ctx, flags, resolved, options) {
+  const skipPreflight = Boolean(options?.skipPreflight);
+  const blockedReasonCode = String(options?.blockedReasonCode || 'SELF_MODE_REQUIRES_BUILD_TX');
+  if (!skipPreflight) {
+    const preflightPayload = buildIntentPayload(flags, {
+      validationOnly: true,
+      forceIdempotency: false,
+      resolvedAction: resolved.resolvedAction,
+      runMode: 'self',
+      mirrorOnly: false,
+    });
+    const preflight = await apiPost(ctx, '/api/v1/agent/execute-intent', preflightPayload);
+    const preflightNormalized = normalizeIntentResponse(preflight);
+    const blockedCount = preflightNormalized.blocked || 0;
+    if (!preflightNormalized.success || blockedCount > 0) {
+      preflightNormalized.success = false;
+      preflightNormalized.error = preflightNormalized.error || 'Preflight blocked self execution';
+      preflightNormalized.preflightBlocked = true;
+      return preflightNormalized;
+    }
+  }
+  if (!shouldUseBuildTxExecution(options?.runMode || 'self', resolved)) {
+    const normalized = normalizeIntentResponse({
+      success: false,
+      status: 'failed',
+      blockedReason: blockedReasonCode,
+      blockedStage: 'routing',
+      error: 'Selected action does not support build-tx self lane. Use --run-mode thirdfy for delegated CEX execution.',
+    });
+    normalized.preflightBlocked = true;
+    return normalized;
+  }
+  const buildTxPayload = buildBuildTxPayload(flags, resolved.resolvedAction);
+  const buildTx = await apiPost(ctx, '/api/v1/agent/build-tx', buildTxPayload);
+  return normalizeIntentResponse({
+    ...buildTx,
+    status: buildTx?.status || 'ready',
+    mode: buildTx?.mode || 'self',
+    unsignedTx: buildTx?.unsignedTx || null,
+    estimatedGas: buildTx?.estimatedGas || null,
+  });
+}
+
+async function executeHybridRun(ctx, flags, resolved, options) {
+  const hybridWalletMode = normalizeHybridWalletMode(options?.hybridWalletMode || flags.hybridWalletMode || 'self');
+  if (hybridWalletMode === 'agent_wallet') {
+    const managedResult = await executeManagedWalletRun(ctx, { ...flags, runMode: 'agent_wallet' }, resolved, options);
+    if (!managedResult.success) {
+      return normalizeIntentResponse({
+        ...managedResult,
+        mode: 'hybrid',
+        hybridWalletMode,
+      });
+    }
+    const mirrorPayload = buildIntentPayload(flags, {
+      validationOnly: true,
+      forceIdempotency: true,
+      resolvedAction: resolved.resolvedAction,
+      runMode: 'hybrid',
+      mirrorOnly: true,
+      hybridWalletMode,
+    });
+    const mirrorResponse = await apiPost(ctx, '/api/v1/agent/execute-intent', mirrorPayload);
+    const mirrorNormalized = normalizeIntentResponse(mirrorResponse);
+    return normalizeIntentResponse({
+      success: Boolean(managedResult.success && mirrorNormalized.success),
+      status: managedResult.status || mirrorNormalized.status || 'queued',
+      mode: 'hybrid',
+      hybridWalletMode,
+      idempotencyKey: managedResult.idempotencyKey || mirrorPayload.idempotencyKey,
+      managed: managedResult,
+      mirror: mirrorNormalized,
+    });
+  }
+  const selfResult = await executeSelfRun(ctx, flags, resolved, {
+    ...(options || {}),
+    runMode: 'hybrid',
+    blockedReasonCode: 'HYBRID_MODE_REQUIRES_BUILD_TX',
+  });
+  if (!selfResult.success) return selfResult;
+
+  const mirrorPayload = buildIntentPayload(flags, {
+    validationOnly: true,
+    forceIdempotency: true,
+    resolvedAction: resolved.resolvedAction,
+    runMode: 'hybrid',
+    mirrorOnly: true,
+  });
+  const mirrorResponse = await apiPost(ctx, '/api/v1/agent/execute-intent', mirrorPayload);
+  const mirrorNormalized = normalizeIntentResponse(mirrorResponse);
+  return normalizeIntentResponse({
+    success: Boolean(selfResult.success && mirrorNormalized.success),
+    status: mirrorNormalized.status || 'ready',
+    mode: 'hybrid',
+    hybridWalletMode,
+    idempotencyKey: mirrorPayload.idempotencyKey,
+    self: selfResult,
+    mirror: mirrorNormalized,
+  });
+}
+
+async function resolveManagedExecutionPreflight(ctx, flags, resolved, options = {}) {
+  const chainId = Number(flags.chainId || 8453);
+  const runMode = String(options.runMode || 'agent_wallet').trim().toLowerCase();
+  const agentApiKey = resolveAgentApiKey(flags, runMode);
+  const userDid = resolveEffectiveUserDid(flags);
+  if (!userDid) {
+    return {
+      success: false,
+      blockedReason: 'MISSING_USER_DID',
+      blockedStage: 'routing',
+      error: 'Managed wallet execution requires --user-did, THIRDFY_USER_DID, or a saved userDid from `thirdfy-agent login email`.',
+      signerMethod: 'managed_wallet_server',
+    };
+  }
+  const tokenIn = resolveTokenInForFunding(getPreparedParams(flags));
+  const query = new URLSearchParams({
+    userDid,
+    chainId: String(chainId),
+    runMode,
+  });
+  if (tokenIn) query.set('tokenIn', tokenIn);
+  const preflightSeed = options.preflightSeed && typeof options.preflightSeed === 'object'
+    ? options.preflightSeed
+    : null;
+  if (preflightSeed && preflightSeed.success === false) {
+    return preflightSeed;
+  }
+  const response = preflightSeed
+    ? {
+      executionWalletAddress: preflightSeed.executionWalletAddress || null,
+      signerMethod: preflightSeed.signerMethod || null,
+      fundingTokenBalance: preflightSeed.fundingTokenBalance || null,
+    }
+    : await apiGet(ctx, `/api/v1/agent/execution-wallet?${query.toString()}`, {
+      'x-agent-api-key': agentApiKey,
+    });
+  const executionWalletAddress = String(response?.executionWalletAddress || '').trim().toLowerCase();
+  const signerMethod = String(response?.signerMethod || 'managed_wallet_server').trim();
+  const rawBalance = String(response?.fundingTokenBalance?.raw || '').trim();
+  let parsedRawBalance = null;
+  if (rawBalance) {
+    try {
+      parsedRawBalance = BigInt(rawBalance);
+    } catch {
+      return {
+        success: false,
+        blockedReason: 'INVALID_FUNDING_BALANCE',
+        blockedStage: 'sizing',
+        error: `Execution wallet ${executionWalletAddress || 'unknown'} returned invalid funding token balance.`,
+        executionWalletAddress,
+        signerMethod,
+        fundingTokenBalance: response?.fundingTokenBalance || null,
+      };
+    }
+  }
+  const expectedWallet = String(flags.walletAddress || flags.executionWalletAddress || '').trim().toLowerCase();
+  const allowWalletMismatch = parseBooleanFlag(flags.allowWalletMismatch, false);
+
+  if (expectedWallet && executionWalletAddress && expectedWallet !== executionWalletAddress && !allowWalletMismatch) {
+    return {
+      success: false,
+      blockedReason: 'EXECUTION_WALLET_MISMATCH',
+      blockedStage: 'routing',
+      error: `Funded wallet (${expectedWallet}) does not match execution wallet (${executionWalletAddress}). Use --allow-wallet-mismatch to override.`,
+      executionWalletAddress,
+      signerMethod,
+      fundingTokenBalance: response?.fundingTokenBalance || null,
+    };
+  }
+
+  if (options.requireFundingCheck && parsedRawBalance !== null && parsedRawBalance <= 0n) {
+    return {
+      success: false,
+      blockedReason: 'INSUFFICIENT_FUNDS',
+      blockedStage: 'sizing',
+      error: `Execution wallet ${executionWalletAddress || 'unknown'} has insufficient tokenIn balance.`,
+      executionWalletAddress,
+      signerMethod,
+      fundingTokenBalance: response?.fundingTokenBalance || null,
+    };
+  }
+
+  return {
+    success: true,
+    executionWalletAddress,
+    signerMethod,
+    fundingTokenBalance: response?.fundingTokenBalance || null,
+    userDid,
+    chainId,
+    tokenIn: tokenIn || null,
+  };
+}
+
+async function performSelfBroadcast(ctx, flags, resolvedAction, selfResult) {
+  const txd = resolveUnsignedTx(selfResult);
+  if (!txd?.to || !txd?.data) {
+    throw createCliError('SELF_UNSIGNED_TX_MISSING', 'Self execution did not return a valid unsigned transaction');
+  }
+  const chainId = Number(txd.chainId || flags.chainId || 8453);
+  const walletAddress = String(flags.walletAddress || process.env.MARKET_MAKER_WALLET_ADDRESS || '').trim();
+  const owsWalletName = String(flags.owsWalletName || process.env.OWS_WALLET_NAME || '').trim();
+  const rpcUrl = String(
+    flags.rpcUrl || process.env.BASE_RPC_URL || process.env.BASE_RPC_HTTP_URL || process.env.RPC_URL || 'https://mainnet.base.org'
+  ).trim();
+  if (!walletAddress) {
+    throw createCliError('SIGNING_FAILED', 'Missing --wallet-address (or MARKET_MAKER_WALLET_ADDRESS) for self-exec signing.');
+  }
+  if (!owsWalletName) {
+    throw createCliError('SIGNING_FAILED', 'Missing --ows-wallet-name (or OWS_WALLET_NAME) for self-exec signing.');
+  }
+
+  const params = getPreparedParams(flags);
+  const effectTokenIn = String(flags.effectTokenIn || params.tokenIn || '').trim();
+  const effectTokenOut = String(flags.effectTokenOut || params.tokenOut || '').trim();
+  const effectMode = normalizeEffectCheckMode(flags.effectCheck || process.env.THIRDFY_EFFECT_CHECK || 'relaxed');
+  const effectRetries = Number(flags.effectCheckRetries || process.env.THIRDFY_EFFECT_CHECK_RETRIES || 2);
+  const effectWaitMs = Number(flags.effectCheckWaitMs || process.env.THIRDFY_EFFECT_CHECK_WAIT_MS || 1200);
+
+  let balancesBefore = null;
+  if (effectMode !== 'off' && effectTokenIn && effectTokenOut) {
+    balancesBefore = await readEffectBalances(rpcUrl, walletAddress, effectTokenIn, effectTokenOut);
+  }
+
+  let submission;
+  try {
+    submission = await signAndBroadcastWithOws({
+      txd,
+      chainId,
+      walletAddress,
+      owsWalletName,
+      rpcUrl,
+    });
+  } catch (error) {
+    throw createCliError('SIGNING_FAILED', error?.message || 'OWS signing failed');
+  }
+
+  let receipt;
+  try {
+    receipt = await submission.sent.wait();
+  } catch (error) {
+    throw createCliError('BROADCAST_FAILED', error?.message || 'Broadcast wait failed');
+  }
+  const status = Number(receipt?.status ?? 0);
+  if (status !== 1) {
+    throw createCliError('BROADCAST_FAILED', 'Transaction receipt status is not success', {
+      receiptStatus: receipt?.status ?? null,
+      txHash: submission.sent.hash,
+    });
+  }
+
+  const effectCheck = await resolveEffectCheckResult({
+    mode: effectMode,
+    rpcUrl,
+    walletAddress,
+    tokenIn: effectTokenIn,
+    tokenOut: effectTokenOut,
+    balancesBefore,
+    retries: effectRetries,
+    waitMs: effectWaitMs,
+  });
+  if (effectCheck.checked && !effectCheck.hasEffect && effectMode === 'strict') {
+    throw createCliError('EFFECT_CHECK_FAILED', 'Transaction mined but did not produce observable token effect.', {
+      txHash: submission.sent.hash,
+      effectCheck,
+      mode: effectMode,
+    });
+  }
+
+  return {
+    txHash: submission.sent.hash,
+    chainId,
+    blockNumber: receipt?.blockNumber ?? null,
+    status: receipt?.status ?? null,
+    unsignedTx: txd,
+    effectCheck,
+    lane: 'self',
+    signer: 'ows',
+    resolvedAction,
+    apiBase: ctx.apiBase,
+  };
+}
+
+async function resolveEffectCheckResult({
+  mode,
+  rpcUrl,
+  walletAddress,
+  tokenIn,
+  tokenOut,
+  balancesBefore,
+  retries,
+  waitMs,
+}) {
+  const baseResult = {
+    checked: true,
+    mode,
+    hasEffect: false,
+    inDeltaRaw: '0',
+    outDeltaRaw: '0',
+    attempts: 0,
+    retries: Math.max(0, Number(retries || 0)),
+  };
+  if (mode === 'off') {
+    return { checked: false, mode, hasEffect: null, inDeltaRaw: null, outDeltaRaw: null, reason: 'disabled' };
+  }
+  if (!tokenIn || !tokenOut || !balancesBefore) {
+    return { checked: false, mode, hasEffect: null, inDeltaRaw: null, outDeltaRaw: null, reason: 'token_pair_missing' };
+  }
+  const maxAttempts = Math.max(1, Number(retries || 0) + 1);
+  let last = null;
+  for (let attempt = 1; attempt <= maxAttempts; attempt += 1) {
+    const balancesAfter = await readEffectBalances(rpcUrl, walletAddress, tokenIn, tokenOut);
+    const inDeltaRaw = (BigInt(balancesBefore.tokenIn) - BigInt(balancesAfter.tokenIn)).toString();
+    const outDeltaRaw = (BigInt(balancesAfter.tokenOut) - BigInt(balancesBefore.tokenOut)).toString();
+    const hasEffect = BigInt(inDeltaRaw) > 0n || BigInt(outDeltaRaw) > 0n;
+    last = {
+      checked: true,
+      mode,
+      hasEffect,
+      inDeltaRaw,
+      outDeltaRaw,
+      attempts: attempt,
+      retries: maxAttempts - 1,
+    };
+    if (hasEffect) return last;
+    if (attempt < maxAttempts) await sleepMs(waitMs);
+  }
+  return {
+    ...(last || baseResult),
+    warning: 'No balance delta observed after retries; treating as non-fatal in relaxed mode.',
+  };
+}
+
+async function submitSignedTx({ rpcUrl, chainId, signedTxHex }) {
+  const ethers = await loadEthers();
+  const { JsonRpcProvider } = ethers;
+  const provider = new JsonRpcProvider(rpcUrl, chainId);
+  const sent = await provider.broadcastTransaction(String(signedTxHex));
+  return sent?.hash || null;
+}
+
+  return {
+    applyExecutionFallbackHints,
+    runPreflightByMode,
+    runExecutionByMode,
+    executeThirdfyRun,
+    executeManagedWalletRun,
+    executeSelfRun,
+    executeHybridRun,
+    resolveManagedExecutionPreflight,
+    performSelfBroadcast,
+    resolveEffectCheckResult,
+    submitSignedTx,
+  };
+}