@sage-protocol/cli 0.8.0 → 0.8.3

package/dist/cli/commands/proposals.js

@@ -7,6 +7,57 @@ const { handleCLIError } = require('../utils/error-handler');
 const subgraphClient = require('../utils/subgraph-client');
 const cliConfig = require('../config');
 
+async function getLogsChunked(provider, filter, maxRange = 50000) {
+  // Default to 50k blocks to stay under most RPC limits (Base Sepolia limits to 100k)
+  const latest = filter.toBlock === 'latest' || typeof filter.toBlock === 'undefined'
+    ? await provider.getBlockNumber()
+    : Number(filter.toBlock);
+  const from = Number(filter.fromBlock || 0);
+  const results = [];
+  for (let start = from; start <= latest; start += maxRange) {
+    const end = Math.min(latest, start + maxRange - 1);
+    try {
+      const batch = await provider.getLogs({ ...filter, fromBlock: start, toBlock: end });
+      if (batch && batch.length) results.push(...batch);
+    } catch (e) {
+      if (process.env.SAGE_VERBOSE === '1') {
+        console.warn(`Log query failed for blocks ${start}-${end}: ${e.message}`);
+      }
+    }
+  }
+  return results;
+}
+
+async function findProposalCreatedLog(provider, govAddr, gov, pid, lookbacks) {
+  const { ethers } = require('ethers');
+  const eventSig = gov.interface.getEvent('ProposalCreated').topicHash;
+  const currentBlock = await provider.getBlockNumber();
+  const pidHex = ethers.hexlify(ethers.toBeHex(pid));
+  for (const span of lookbacks) {
+    const from = currentBlock > span ? currentBlock - span : 0;
+    let logs = await getLogsChunked(provider, {
+      topics: [eventSig, ethers.zeroPadValue(pidHex, 32)],
+      address: govAddr,
+      fromBlock: from,
+      toBlock: 'latest'
+    });
+    if (!logs.length) {
+      const all = await getLogsChunked(provider, { topics: [eventSig], address: govAddr, fromBlock: from, toBlock: 'latest' });
+      for (const l of all) {
+        try {
+          const p = gov.interface.parseLog(l);
+          if (p && p.name === 'ProposalCreated' && BigInt(p.args.proposalId.toString()) === pid) {
+            logs = [l];
+            break;
+          }
+        } catch { }
+      }
+    }
+    if (logs.length) return logs[0];
+  }
+  return null;
+}
+
 function register(program) {
   const cmd = new Command('proposals')
     .description('Proposals navigation: inbox, preview, vote, execute');
@@ -219,10 +270,92 @@ function register(program) {
               if (summary.description) ui.output(` Description: ${summary.description.slice(0, 100)}...`);
             }
           } catch (e) {
-            // Final fallback: minimal info
             if (process.env.SAGE_VERBOSE === '1') {
               ui.warn(`SDK getProposalDetails failed: ${e.message}`);
             }
+            // Fallback 1: try subgraph directly (no block range limits)
+            let foundViaSubgraph = false;
+            try {
+              const status = await subgraphClient.checkSubgraphStatus(provider);
+              if (status.available && ctx.governor) {
+                const proposals = await subgraphClient.getProposals(ctx.governor, { first: 200 });
+                const pidDec = pid.toString();
+                const match = proposals.find((p) => {
+                  const parts = String(p.id || '').split('-');
+                  const last = parts.length > 1 ? parts[parts.length - 1] : String(p.id || '');
+                  if (!last) return false;
+                  if (last === pidDec) return true;
+                  try { if (String(last).startsWith('0x') && BigInt(String(last)) === pid) return true; } catch (_) { }
+                  return false;
+                });
+                if (match && match.targets?.length) {
+                  const targets = Array.from(match.targets || [], (a) => String(a));
+                  const values = Array.from(match.values || [], (v) => BigInt(String(v || 0)));
+                  const calldatas = Array.from(match.calldatas || [], (b) => String(b));
+                  const description = String(match.description || '');
+                  const selectors = calldatas.map((d) => (typeof d === 'string' ? d.slice(0, 10) : '0x'));
+                  const summary = {
+                    id: pid.toString(),
+                    source: 'subgraph',
+                    actionCount: targets.length,
+                    targets,
+                    values: values.map((v) => v.toString()),
+                    selectors,
+                    description
+                  };
+                  if (opts.json) ui.json(withJsonVersion(summary));
+                  else {
+                    ui.output(`Proposal ${summary.id} (subgraph)`);
+                    ui.output(` Actions: ${summary.actionCount}`);
+                    if (summary.targets.length) ui.output(` First target: ${summary.targets[0]}`);
+                    if (summary.selectors.length) ui.output(` First selector: ${summary.selectors[0]}`);
+                    if (summary.description) ui.output(` Description: ${summary.description.slice(0, 100)}...`);
+                  }
+                  foundViaSubgraph = true;
+                }
+              }
+            } catch (sgErr) {
+              if (process.env.SAGE_VERBOSE === '1') {
+                ui.warn(`Subgraph fallback failed: ${sgErr.message}`);
+              }
+            }
+            if (foundViaSubgraph) return;
+
+            // Fallback 2: scan ProposalCreated logs with chunked queries
+            try {
+              if (ctx.governor) {
+                const GovABI = require('../utils/artifacts').resolveArtifact('contracts/cloneable/PromptGovernorCloneable.sol/PromptGovernorCloneable.json').abi;
+                const gov = new ethers.Contract(ctx.governor, GovABI, provider);
+                const hit = await findProposalCreatedLog(provider, ctx.governor, gov, pid, [20000, 100000, 500000]);
+                if (hit) {
+                  const parsed = gov.interface.parseLog(hit);
+                  const targets = Array.from(parsed.args.targets || [], (a) => String(a));
+                  const values = Array.from(parsed.args.values || [], (v) => BigInt(v.toString()));
+                  const calldatas = Array.from(parsed.args.calldatas || [], (b) => ethers.hexlify(b));
+                  const description = String(parsed.args.description ?? '');
+                  const selectors = calldatas.map((d) => (typeof d === 'string' ? d.slice(0, 10) : '0x'));
+                  const summary = {
+                    id: pid.toString(),
+                    source: 'logs',
+                    actionCount: targets.length,
+                    targets,
+                    values: values.map((v) => v.toString()),
+                    selectors,
+                    description
+                  };
+                  if (opts.json) ui.json(withJsonVersion(summary));
+                  else {
+                    ui.output(`Proposal ${summary.id} (logs)`);
+                    ui.output(` Actions: ${summary.actionCount}`);
+                    if (summary.targets.length) ui.output(` First target: ${summary.targets[0]}`);
+                    if (summary.selectors.length) ui.output(` First selector: ${summary.selectors[0]}`);
+                    if (summary.description) ui.output(` Description: ${summary.description.slice(0, 100)}...`);
+                  }
+                  return;
+                }
+              }
+            } catch (_) { }
+            // Final fallback: minimal info
             const summary = { id: pid.toString(), description: '(unable to fetch proposal details)' };
             if (opts.json) ui.json(withJsonVersion(summary));
             else ui.output(`Proposal ${summary.id} - ${summary.description}`);
@@ -795,10 +928,27 @@ function register(program) {
             return;
         }
 
-        // Delegate to existing library-manager execute flow if it is a library update; otherwise, try queue/execute via gm
+        // Queue only when needed; skip queue if already queued
+        let stateNum = null;
+        let stateName = 'unknown';
         try {
-          await gm.queueProposal(id);
+          const state = await gm.governor.state(gm.normalizeProposalId(id));
+          stateNum = Number(state);
+          stateName = gm.getStateName ? gm.getStateName(stateNum) : String(stateNum);
         } catch (_) {}
+
+        if (stateNum === 4) {
+          try {
+            await gm.queueProposal(id);
+          } catch (_) {}
+        } else if (stateNum === 5) {
+          if (!process.env.SAGE_QUIET_JSON) {
+            console.log(`ℹ️  Proposal already queued (state ${stateName}). Skipping queue step.`);
+          }
+        } else if (stateNum !== null && !process.env.SAGE_QUIET_JSON) {
+          console.log(`⚠️  Proposal is in state ${stateName}; queue may fail.`);
+        }
+
         await gm.executeProposal(id);
         ui.success('Execute complete');
       } catch (e) {

package/dist/cli/commands/stake-status.js

@@ -11,19 +11,21 @@ function register(program) {
   .option('--governor <address>', 'Governor address to check')
   .option('--address <address>', 'Address to check (defaults to connected wallet)')
   .option('-v, --verbose', 'Show detailed output')
+  .option('--json', 'Output JSON', false)
   .action(async (opts) => {
     try {
-      ui.configure({ verbose: opts.verbose });
+      ui.configure({ verbose: opts.verbose, json: opts.json });
+      const show = !opts.json;
 
       const WalletManager = require('../wallet-manager');
       const { resolveGovContext } = require('../utils/gov-context');
 
       const invokedAsStakeStatus = process.argv.includes('stake-status');
-      if (invokedAsStakeStatus) {
+      if (invokedAsStakeStatus && show) {
         ui.warn('`sage stake-status` is deprecated. Use `sage voting-status` (governance uses delegation, not staking).');
       }
 
-      const rpcUrl = process.env.RPC_URL || process.env.BASE_SEPOLIA_RPC || 'https://base-sepolia.publicnode.com';
+      const rpcUrl = process.env.SAGE_RPC_URL || process.env.RPC_URL || process.env.BASE_SEPOLIA_RPC || 'https://base-sepolia.publicnode.com';
       const provider = new ethers.JsonRpcProvider(rpcUrl);
 
       // Get wallet manager and connect
@@ -32,11 +34,13 @@ function register(program) {
       const signer = walletManager.getSigner();
       const address = opts.address || await signer.getAddress();
 
-      ui.header('Voting Power Status');
-      ui.keyValue([
-        ['Address', address],
-        ['RPC', rpcUrl]
-      ]);
+      if (show) {
+        ui.header('Voting Power Status');
+        ui.keyValue([
+          ['Address', address],
+          ['RPC', rpcUrl]
+        ]);
+      }
       
       // Resolve governance context
       const ctx = await resolveGovContext({ 
@@ -48,14 +52,17 @@ function register(program) {
       });
       
       if (!ctx.governor) {
-        ui.error('No Governor found');
+        if (show) ui.error('No Governor found');
+        else ui.json({ ok: false, error: 'No Governor found' });
         return;
       }
 
-      ui.keyValue([
-        ['Governor', ctx.governor],
-        ['SubDAO', ctx.subdao || 'N/A']
-      ]);
+      if (show) {
+        ui.keyValue([
+          ['Governor', ctx.governor],
+          ['SubDAO', ctx.subdao || 'N/A']
+        ]);
+      }
       
       // Get Governor's voting token and multiplier status
       const govABI = [
@@ -78,19 +85,21 @@ function register(program) {
       const baseVotesTokenAddr = await governor.baseVotesToken().catch(() => votingToken);
       const isWrapperMode = isMultiplierEnabled || (baseVotesTokenAddr && baseVotesTokenAddr !== votingToken);
 
-      if (isWrapperMode) {
-        ui.keyValue([
-          ['Voting Token (wrapper)', votingToken],
-          ['Base Token (SXXX)', baseVotesTokenAddr],
-          ['NFT Multipliers', isMultiplierEnabled ? 'Enabled' : 'Unknown']
-        ]);
-      } else {
-        ui.keyValue([
-          ['Voting Token', votingToken],
-          ['NFT Multipliers', 'Disabled']
-        ]);
+      if (show) {
+        if (isWrapperMode) {
+          ui.keyValue([
+            ['Voting Token (wrapper)', votingToken],
+            ['Base Token (SXXX)', baseVotesTokenAddr],
+            ['NFT Multipliers', isMultiplierEnabled ? 'Enabled' : 'Unknown']
+          ]);
+        } else {
+          ui.keyValue([
+            ['Voting Token', votingToken],
+            ['NFT Multipliers', 'Disabled']
+          ]);
+        }
+        ui.info(`Proposal Threshold: ${ethers.formatEther(threshold)} tokens`);
       }
-      ui.info(`Proposal Threshold: ${ethers.formatEther(threshold)} tokens`);
       
       // In multiplier mode, governor.token() is an IVotes wrapper (MultipliedVotes) which is NOT an ERC20,
       // so ERC20 calls (name/symbol/decimals/balanceOf) can revert. Always read ERC20 metadata from the base token.
@@ -117,35 +126,39 @@ function register(program) {
         provider.getBlockNumber()
       ]);
       
-      ui.newline();
-      ui.header('Token Details');
-      ui.keyValue([
-        ['Name', name],
-        ['Symbol', symbol],
-        ['Decimals', decimals],
-        ['Balance', `${ethers.formatUnits(balance, decimals)} ${symbol}`],
-        ['Delegates to', delegates]
-      ]);
+      if (show) {
+        ui.newline();
+        ui.header('Token Details');
+        ui.keyValue([
+          ['Name', name],
+          ['Symbol', symbol],
+          ['Decimals', decimals],
+          ['Balance', `${ethers.formatUnits(balance, decimals)} ${symbol}`],
+          ['Delegates to', delegates]
+        ]);
+      }
       
       // Check voting power at different blocks
       const blocksToCheck = [currentBlock - 1, currentBlock - 2, currentBlock - 5];
-      ui.newline();
-      ui.header('Voting Power History');
+      if (show) {
+        ui.newline();
+        ui.header('Voting Power History');
+      }
 
       for (const block of blocksToCheck) {
         try {
           const votes = await votesToken.getPastVotes(address, block);
           const formattedVotes = ethers.formatUnits(votes, decimals);
           const status = votes >= threshold ? ui.symbols.check : ui.symbols.cross;
-          ui.output(`   Block ${block}: ${formattedVotes} ${symbol} ${status}`);
+          if (show) ui.output(`   Block ${block}: ${formattedVotes} ${symbol} ${status}`);
         } catch (e) {
-          ui.output(`   Block ${block}: Error - ${e.message}`);
+          if (show) ui.output(`   Block ${block}: Error - ${e.message}`);
         }
       }
       
       // Note: stakeToken() removed from SubDAO contracts (threshold-based governance)
       // Voting power now comes from SXXX token delegation, not staking
-      if (ctx.subdao) {
+      if (ctx.subdao && show) {
         ui.newline();
         ui.header('Governance Model');
         ui.output('   This SubDAO uses threshold-based governance.');
@@ -154,8 +167,10 @@ function register(program) {
       
       // Summary
       const currentVotes = await votesToken.getPastVotes(address, currentBlock - 1).catch(() => 0n);
-      ui.newline();
-      ui.header('Summary');
+      if (show) {
+        ui.newline();
+        ui.header('Summary');
+      }
 
       // If multipliers are enabled, show both base and effective voting power
       if (isWrapperMode) {
@@ -163,32 +178,91 @@ function register(program) {
           const [baseVotes, multiplier, effectiveVotes] = await governor.getVotingBreakdown(address);
           const multiplierDisplay = (Number(multiplier) / 10000).toFixed(2);
           const canPropose = effectiveVotes >= threshold;
-          ui.keyValue([
-            ['Base Voting Power', `${ethers.formatUnits(baseVotes, decimals)} ${symbol}`],
-            ['NFT Multiplier', `${multiplierDisplay}x`],
-            ['Effective Voting Power', `${ethers.formatUnits(effectiveVotes, decimals)} votes`],
-            ['Proposal Threshold', `${ethers.formatEther(threshold)} tokens`],
-            ['Can Propose', canPropose ? 'YES' : 'NO']
-          ]);
+          if (show) {
+            ui.keyValue([
+              ['Base Voting Power', `${ethers.formatUnits(baseVotes, decimals)} ${symbol}`],
+              ['NFT Multiplier', `${multiplierDisplay}x`],
+              ['Effective Voting Power', `${ethers.formatUnits(effectiveVotes, decimals)} votes`],
+              ['Proposal Threshold', `${ethers.formatEther(threshold)} tokens`],
+              ['Can Propose', canPropose ? 'YES' : 'NO']
+            ]);
+          } else {
+            ui.json({
+              ok: true,
+              address,
+              rpcUrl,
+              governor: ctx.governor,
+              subdao: ctx.subdao || null,
+              votingToken,
+              baseToken: baseVotesTokenAddr,
+              isMultiplierEnabled: !!isMultiplierEnabled,
+              threshold: threshold.toString(),
+              balance: balance.toString(),
+              delegates,
+              baseVotes: baseVotes.toString(),
+              multiplier: multiplier.toString(),
+              effectiveVotes: effectiveVotes.toString(),
+              canPropose
+            });
+            return;
+          }
         } catch (e) {
           // Fallback if getVotingBreakdown fails
           const canPropose = currentVotes >= threshold;
+          if (show) {
+            ui.keyValue([
+              ['Current Voting Power', `${ethers.formatUnits(currentVotes, decimals)} ${symbol}`],
+              ['Proposal Threshold', `${ethers.formatEther(threshold)} tokens`],
+              ['Can Propose', canPropose ? 'YES' : 'NO']
+            ]);
+          } else {
+            ui.json({
+              ok: true,
+              address,
+              rpcUrl,
+              governor: ctx.governor,
+              subdao: ctx.subdao || null,
+              votingToken,
+              baseToken: baseVotesTokenAddr,
+              isMultiplierEnabled: !!isMultiplierEnabled,
+              threshold: threshold.toString(),
+              balance: balance.toString(),
+              delegates,
+              currentVotes: currentVotes.toString(),
+              canPropose
+            });
+            return;
+          }
+        }
+      } else {
+        const canPropose = currentVotes >= threshold;
+        if (show) {
           ui.keyValue([
             ['Current Voting Power', `${ethers.formatUnits(currentVotes, decimals)} ${symbol}`],
             ['Proposal Threshold', `${ethers.formatEther(threshold)} tokens`],
             ['Can Propose', canPropose ? 'YES' : 'NO']
           ]);
+        } else {
+          ui.json({
+            ok: true,
+            address,
+            rpcUrl,
+            governor: ctx.governor,
+            subdao: ctx.subdao || null,
+            votingToken,
+            baseToken: baseVotesTokenAddr,
+            isMultiplierEnabled: !!isMultiplierEnabled,
+            threshold: threshold.toString(),
+            balance: balance.toString(),
+            delegates,
+            currentVotes: currentVotes.toString(),
+            canPropose
+          });
+          return;
         }
-      } else {
-        const canPropose = currentVotes >= threshold;
-        ui.keyValue([
-          ['Current Voting Power', `${ethers.formatUnits(currentVotes, decimals)} ${symbol}`],
-          ['Proposal Threshold', `${ethers.formatEther(threshold)} tokens`],
-          ['Can Propose', canPropose ? 'YES' : 'NO']
-        ]);
       }
       
-      if (currentVotes < threshold) {
+      if (show && currentVotes < threshold) {
         ui.newline();
         ui.info('To gain voting power:');
         if (balance === 0n) {

package/dist/cli/commands/sxxx.js

@@ -22,10 +22,14 @@ function register(program) {
           try {
             ui.configure({ verbose: opts.verbose });
             const { ethers } = require('ethers');
-            const rpcUrl = cliConfig.resolveRpcUrl();
+            const rpcUrl = cliConfig.resolveRpcUrl({ allowEnv: true });
             const provider = new ethers.JsonRpcProvider(rpcUrl);
             const tokenAddress = cliConfig.resolveAddress('SXXX_TOKEN_ADDRESS');
             if (!tokenAddress) throw new Error('SXXX_TOKEN_ADDRESS not set');
+            const code = await provider.getCode(tokenAddress);
+            if (!code || code === '0x' || code === '0x0') {
+              throw new Error(`SXXX contract not found at ${tokenAddress}. Check SAGE_RPC_URL/CHAIN_ID or import addresses.`);
+            }
             let targetAddress = address;
             // 1) Prefer configured default account from profile
             if (!targetAddress) {
@@ -46,9 +50,38 @@ function register(program) {
               } catch (_) {}
             }
             if (!targetAddress) throw new Error('No address provided and could not resolve wallet account');
-            const abi = ['function balanceOf(address) view returns (uint256)'];
+            const abi = ['function balanceOf(address) view returns (uint256)', 'function symbol() view returns (string)'];
             const token = new ethers.Contract(tokenAddress, abi, provider);
-            const bal = await token.balanceOf(targetAddress);
+
+            // Verify contract exists and is an ERC20
+            try {
+              const code = await provider.getCode(tokenAddress);
+              if (code === '0x') {
+                ui.error(`SXXX contract not deployed at ${tokenAddress}`);
+                ui.info('   This may mean the address is incorrect or the network is wrong.');
+                ui.info('   Check: RPC_URL, SXXX_TOKEN_ADDRESS, or run `sage doctor` for diagnostics.');
+                process.exit(1);
+              }
+            } catch (codeErr) {
+              // Ignore code check failure, proceed with balance check
+            }
+
+            let bal;
+            try {
+              bal = await token.balanceOf(targetAddress);
+            } catch (balErr) {
+              const errMsg = balErr.message || String(balErr);
+              if (errMsg.includes('BAD_DATA') || errMsg.includes('could not decode result')) {
+                ui.error(`Contract at ${tokenAddress} returned invalid data for balanceOf()`);
+                ui.info('   This usually means the address is not an ERC20 token contract.');
+                ui.info('   Possible fixes:');
+                ui.info('     - Check SXXX_TOKEN_ADDRESS is correct for your network');
+                ui.info('     - Verify RPC_URL points to the correct chain (Base Sepolia)');
+                ui.info('     - Run `sage doctor` for full diagnostics');
+                process.exit(1);
+              }
+              throw balErr;
+            }
             ui.success(`SXXX Balance for ${ui.formatAddress(targetAddress)}: ${ui.formatToken(bal, { symbol: 'SXXX' })}`);
           } catch (error) {
             handleCLIError('sxxx:balance', error, { exit: true });
@@ -62,7 +95,7 @@ function register(program) {
         .action(async (opts) => {
           try {
             ui.configure({ verbose: opts.verbose });
-            const rpcUrl = cliConfig.resolveRpcUrl();
+            const rpcUrl = cliConfig.resolveRpcUrl({ allowEnv: true });
             const tokenAddress = cliConfig.resolveAddress('SXXX_TOKEN_ADDRESS');
             if (!tokenAddress) throw new Error('SXXX_TOKEN_ADDRESS not set (configure via .env or .sage profile)');
             const provider = new ethers.JsonRpcProvider(rpcUrl);

package/dist/cli/commands/wallet.js

@@ -289,9 +289,10 @@ const Web3AuthWalletManager = require('../web3auth-wallet-manager');
             }
 
             // Device code flow via relay works with just appId (no secret needed)
-            // Only --local mode requires appSecret for direct Privy SDK calls
+            // Always prefer relay unless --local is explicitly set
             if (appId) {
               if (options?.local) {
+                process.env.SAGE_PRIVY_LOGIN_MODE = 'local';
                 // Local OAuth requires appSecret for direct Privy SDK authentication
                 if (!appSecret) {
                   ui.error('Local OAuth mode requires PRIVY_APP_SECRET.');
@@ -300,15 +301,9 @@ const Web3AuthWalletManager = require('../web3auth-wallet-manager');
                 }
                 ui.info('Using local OAuth authentication...');
               } else {
-                // Web/device code flow - uses relay, no secret needed
-                // Force device code mode when secret is not available
-                if (!appSecret) {
-                  process.env.SAGE_PRIVY_LOGIN_MODE = 'device';
-                  ui.info('Using device code authentication via web app relay...');
-                } else {
-                  process.env.SAGE_PRIVY_LOGIN_MODE = 'web';
-                  ui.info('Using web-based authentication...');
-                }
+                // Web relay flow - uses web app, no localhost callback
+                process.env.SAGE_PRIVY_LOGIN_MODE = 'web';
+                ui.info('Using web-based authentication via relay...');
               }
 
               const walletManager = new PrivyAuthWalletManager();

package/dist/cli/contracts/index.js

@@ -8,7 +8,8 @@
 const { ethers } = require('ethers');
 
 // Default RPC URL
-const DEFAULT_RPC = process.env.RPC_URL
+const DEFAULT_RPC = process.env.SAGE_RPC_URL
+  || process.env.RPC_URL
   || process.env.BASE_SEPOLIA_RPC
   || 'https://base-sepolia.publicnode.com';
 

package/dist/cli/index.js

@@ -19,6 +19,11 @@ if (!process.env.CONTRACT_ARTIFACTS_ROOT) {
   }
 }
 
+// Always trust SAGE_RPC_URL over RPC_URL when provided
+if (process.env.SAGE_RPC_URL) {
+  process.env.RPC_URL = process.env.SAGE_RPC_URL;
+}
+
 // Filter out deprecated Lit SDK warning immediately
 const realStderrWrite = process.stderr.write.bind(process.stderr);
 process.stderr.write = (chunk, encoding, callback) => {

package/dist/cli/privy-auth-wallet-manager.js

@@ -82,7 +82,9 @@ class PrivyAuthWalletManager {
     try {
       const relayEnabled = process.env.SAGE_DISABLE_PRIVY_RELAY !== '1';
       const hasAppSecret = !!this.appSecret;
-      const preferSessionFlow = relayEnabled && !hasAppSecret;
+      const mode = String(process.env.SAGE_PRIVY_LOGIN_MODE || '').trim().toLowerCase();
+      const forceRelay = relayEnabled && mode !== 'local' && mode !== 'oauth';
+      const preferSessionFlow = forceRelay;
 
       // Try cached credentials first
       const cached = readPrivyCredentials();
@@ -140,7 +142,6 @@ class PrivyAuthWalletManager {
 
       // No valid cached credentials - need OAuth login
       console.log('\nNo cached Privy credentials found.');
-      const mode = String(process.env.SAGE_PRIVY_LOGIN_MODE || '').trim().toLowerCase();
       const useSessionFlow = preferSessionFlow || mode === 'web' || mode === 'session';
       const useDeviceCodeFlow = !preferSessionFlow && (mode === 'device' || mode === 'device_code');
 

package/dist/cli/services/config/chain-defaults.js

@@ -58,7 +58,7 @@ const CHAIN_CONFIGS = {
  * Used for resolution precedence.
  */
 const ENV_VARS = {
-  rpcUrl: ['RPC_URL', 'BASE_SEPOLIA_RPC', 'BASE_RPC_URL'],
+  rpcUrl: ['SAGE_RPC_URL', 'RPC_URL', 'BASE_SEPOLIA_RPC', 'BASE_RPC_URL'],
   chainId: ['CHAIN_ID', 'BASE_CHAIN_ID'],
   subgraphUrl: ['SUBGRAPH_URL', 'SAGE_SUBGRAPH_URL', 'NEXT_PUBLIC_GRAPH_ENDPOINT', 'NEXT_PUBLIC_SUBGRAPH_URL']
 };

package/dist/cli/services/config/manager.js

@@ -121,6 +121,9 @@ class ConfigManager {
       if (fs.existsSync(sageEnv)) {
         dotenv.config({ path: sageEnv });
       }
+      if (process.env.SAGE_RPC_URL) {
+        process.env.RPC_URL = process.env.SAGE_RPC_URL;
+      }
     } catch (_) {
       // dotenv not available, skip
     }

package/dist/cli/services/config/schema.js

@@ -105,6 +105,7 @@ const addressMap = z.record(
  */
 const ipfsConfig = z.object({
   gateway: z.string().url().optional(),
+  gateways: z.array(z.string()).optional(),
   pinataApiKey: z.string().optional(),
   pinataSecretKey: z.string().optional(),
   pinataJwt: z.string().optional(),

package/dist/cli/services/ipfs/onboarding.js

@@ -2,6 +2,12 @@ const path = require('path');
 const ui = require('../../utils/cli-ui');
 
 const DEFAULT_GATEWAY = 'https://ipfs.dev.sageprotocol.io/ipfs';
+const FALLBACK_GATEWAYS = [
+  'https://dweb.link/ipfs',
+  'https://nftstorage.link/ipfs',
+  'https://ipfs.io/ipfs',
+  'https://gateway.pinata.cloud/ipfs'
+];
 const DEFAULT_WORKER_BASE = 'https://api.sageprotocol.io';
 const DEFAULT_WORKER_CHALLENGE_PATH = '/ipfs/auth/challenge';
 const DEFAULT_WORKER_UPLOAD_PATH = '/ipfs/upload';
@@ -87,6 +93,7 @@ function createIpfsOnboarding({
 
     if (!quiet) {
       ui.header('Sage IPFS pinning setup', 'Configure your gateway and pinning providers so uploads work out of the box.');
+      ui.output(`Gateway fallbacks: ${FALLBACK_GATEWAYS.join(', ')}`);
     }
 
     let scope = initialScope && ['project', 'global'].includes(initialScope) ? initialScope : null;
@@ -332,6 +339,10 @@ function createIpfsOnboarding({
     const payload = {};
     if (gateway !== undefined) {
       payload.gateway = ensureString(gateway) || null;
+      if (payload.gateway) {
+        const fallback = FALLBACK_GATEWAYS.filter((g) => g !== payload.gateway);
+        payload.gateways = fallback;
+      }
     }
     payload.warmGateway = !!warmGateway;
     if (provider) payload.provider = provider;