@grimoirelabs/cli 0.8.0 → 0.10.0

package/dist/commands/cast.d.ts

@@ -21,7 +21,14 @@ interface CastOptions {
     mnemonic?: string;
     keystore?: string;
     passwordEnv?: string;
-    rpcUrl?: string;
+    rpcUrl?: string | string[];
+    destinationSpell?: string;
+    destinationChain?: string;
+    handoffTimeoutSec?: string;
+    pollIntervalSec?: string;
+    watch?: boolean;
+    morphoMarketId?: string | string[];
+    morphoMarketMap?: string;
     gasMultiplier?: string;
     skipConfirm?: boolean;
     verbose?: boolean;

package/dist/commands/cast.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cast.d.ts","sourceRoot":"","sources":["../../src/commands/cast.ts"],"names":[],"mappings":"AAAA;;;GAGG;AA4CH,UAAU,WAAW;IACnB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,gBAAgB,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC;IACrC,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,gBAAgB,CAAC,EAAE,KAAK,GAAG,KAAK,GAAG,QAAQ,GAAG,MAAM,CAAC;IACrD,aAAa,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,QAAQ,CAAC;IAC3C,oBAAoB,CAAC,EAAE,OAAO,CAAC;IAC/B,UAAU,CAAC,EAAE,MAAM,CAAC;IAEpB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,WAAW,CAAC,EAAE,MAAM,CAAC;IAErB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,WAAW,CAAC,EAAE,OAAO,CAAC;IAEtB,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,IAAI,CAAC,EAAE,OAAO,CAAC;IAEf,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,OAAO,CAAC,EAAE,OAAO,CAAC;IAElB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,OAAO,CAAC,EAAE,MAAM,CAAC;IAEjB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AAED,wBAAsB,WAAW,CAAC,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC,CA+HxF"}
+{"version":3,"file":"cast.d.ts","sourceRoot":"","sources":["../../src/commands/cast.ts"],"names":[],"mappings":"AAAA;;;GAGG;AA+DH,UAAU,WAAW;IACnB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,gBAAgB,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC;IACrC,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,gBAAgB,CAAC,EAAE,KAAK,GAAG,KAAK,GAAG,QAAQ,GAAG,MAAM,CAAC;IACrD,aAAa,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,QAAQ,CAAC;IAC3C,oBAAoB,CAAC,EAAE,OAAO,CAAC;IAC/B,UAAU,CAAC,EAAE,MAAM,CAAC;IAEpB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,WAAW,CAAC,EAAE,MAAM,CAAC;IAErB,MAAM,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC;IAC3B,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,cAAc,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC;IACnC,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,WAAW,CAAC,EAAE,OAAO,CAAC;IAEtB,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,IAAI,CAAC,EAAE,OAAO,CAAC;IAEf,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,OAAO,CAAC,EAAE,OAAO,CAAC;IAElB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,OAAO,CAAC,EAAE,MAAM,CAAC;IAEjB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AAED,wBAAsB,WAAW,CAAC,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC,CA+IxF"}

package/dist/commands/cast.js

@@ -7,7 +7,7 @@ import { homedir } from "node:os";
 import { join } from "node:path";
 import * as readline from "node:readline";
 import { Writable } from "node:stream";
-import { compileFile, createProvider, createWalletFromConfig, execute, formatWei, getChainName, getNativeCurrencySymbol, isTestnet, loadPrivateKey, } from "@grimoirelabs/core";
+import { SqliteStateStore, compileFile, createProvider, createRunRecord, createWalletFromConfig, execute, formatWei, getChainName, getNativeCurrencySymbol, isTestnet, loadPrivateKey, orchestrateCrossChain, toCrossChainReceipt, } from "@grimoirelabs/core";
 import { adapters, createHyperliquidAdapter } from "@grimoirelabs/venues";
 import chalk from "chalk";
 import ora from "ora";
@@ -15,6 +15,7 @@ import { hydrateParamsFromEnsProfile, resolveEnsProfile } from "../lib/ens-profi
 import { resolveAdvisorSkillsDirs } from "./advisor-skill-helpers.js";
 import { resolveAdvisoryHandler } from "./advisory-handlers.js";
 import { createAdvisoryLiveTraceLogger } from "./advisory-live-trace.js";
+import { createLogicalRunId, parseMorphoMarketMappings, parseRpcUrlMappings, requireExplicitRpcMappings, resolveRpcUrlForChain, validateMorphoMappingsForSpells, } from "./cross-chain-helpers.js";
 import { buildRuntimeProvenanceManifest, enforceFreshnessPolicy, resolveDataPolicy, resolveReplayParams, } from "./data-provenance.js";
 import { buildRunReportEnvelope, formatRunReportText } from "./run-report.js";
 import { withStatePersistence } from "./state-helpers.js";
@@ -90,6 +91,21 @@ export async function castCommand(spellPath, options) {
         const chainId = Number.parseInt(options.chain ?? "1", 10);
         const chainName = getChainName(chainId);
         const isTest = isTestnet(chainId);
+        if (options.destinationSpell) {
+            await executeCrossChainCast({
+                sourceSpellPath: spellPath,
+                sourceSpell: spell,
+                sourceChainId: chainId,
+                params,
+                options,
+                noState,
+                mode,
+                hasKey,
+                dataPolicy,
+                replayResolution,
+            });
+            return;
+        }
         console.log();
         console.log(chalk.cyan("🔗 Network:"));
         console.log(`  ${chalk.dim("Chain:")} ${chainName} (${chainId})`);
@@ -153,7 +169,7 @@ async function executeWithWallet(spell, params, options, noState, chainId, isTes
     catch {
         // Keep default adapters if key extraction fails.
     }
-    const rpcUrl = options.rpcUrl ?? process.env.RPC_URL;
+    const rpcUrl = resolveRpcUrlFromOption(chainId, options.rpcUrl);
     if (!rpcUrl) {
         spinner.warn(chalk.yellow("No RPC URL provided, using default public RPC"));
     }
@@ -365,6 +381,394 @@ async function executeSimulation(spell, params, options, noState, chainId, runti
         process.exit(1);
     }
 }
+async function executeCrossChainCast(input) {
+    const destinationSpellPath = input.options.destinationSpell;
+    if (!destinationSpellPath) {
+        throw new Error("Cross-chain mode requires --destination-spell");
+    }
+    const destinationChainId = parseRequiredNumber(input.options.destinationChain, "--destination-chain");
+    const handoffTimeoutSec = parseRequiredNumber(input.options.handoffTimeoutSec, "--handoff-timeout-sec");
+    const pollIntervalSec = input.options.pollIntervalSec
+        ? parseRequiredNumber(input.options.pollIntervalSec, "--poll-interval-sec")
+        : 30;
+    const destinationCompile = await compileFile(destinationSpellPath);
+    if (!destinationCompile.success || !destinationCompile.ir) {
+        throw new Error(`Destination spell compilation failed: ${destinationCompile.errors.map((e) => `[${e.code}] ${e.message}`).join("; ")}`);
+    }
+    const destinationSpell = destinationCompile.ir;
+    const rpcMappings = parseRpcUrlMappings(input.options.rpcUrl);
+    requireExplicitRpcMappings(rpcMappings, input.sourceChainId, destinationChainId);
+    const sourceRpcUrl = resolveRpcUrlForChain(input.sourceChainId, rpcMappings);
+    const destinationRpcUrl = resolveRpcUrlForChain(destinationChainId, rpcMappings);
+    if (!sourceRpcUrl || !destinationRpcUrl) {
+        throw new Error("Could not resolve RPC URLs for both source and destination chains.");
+    }
+    const morphoMarketIds = parseMorphoMarketMappings({
+        morphoMarketId: input.options.morphoMarketId,
+        morphoMarketMap: input.options.morphoMarketMap,
+    });
+    validateMorphoMappingsForSpells(input.sourceSpell, destinationSpell, morphoMarketIds);
+    const sourceProvider = createProvider(input.sourceChainId, sourceRpcUrl);
+    const destinationProvider = createProvider(destinationChainId, destinationRpcUrl);
+    const spinner = ora("Preparing cross-chain orchestration...").start();
+    let keyConfig;
+    let configuredAdapters = adapters;
+    let sourceWallet;
+    let destinationWallet;
+    if (input.mode === "execute") {
+        keyConfig = await resolveKeyConfig(input.options, spinner);
+        try {
+            const rawKey = loadPrivateKey(keyConfig);
+            configuredAdapters = adapters.map((adapter) => {
+                if (adapter.meta.name === "hyperliquid") {
+                    return createHyperliquidAdapter({
+                        privateKey: rawKey,
+                        assetMap: { ETH: 4 },
+                    });
+                }
+                return adapter;
+            });
+        }
+        catch {
+            configuredAdapters = adapters;
+        }
+        sourceWallet = createWalletFromConfig(keyConfig, input.sourceChainId, sourceProvider.rpcUrl);
+        destinationWallet = createWalletFromConfig(keyConfig, destinationChainId, destinationProvider.rpcUrl);
+    }
+    else if (input.hasKey) {
+        keyConfig = await resolveKeyConfig(input.options, spinner);
+        try {
+            const rawKey = loadPrivateKey(keyConfig);
+            configuredAdapters = adapters.map((adapter) => {
+                if (adapter.meta.name === "hyperliquid") {
+                    return createHyperliquidAdapter({
+                        privateKey: rawKey,
+                        assetMap: { ETH: 4 },
+                    });
+                }
+                return adapter;
+            });
+        }
+        catch {
+            configuredAdapters = adapters;
+        }
+    }
+    const vault = resolveVaultAddress(input.options.vault, sourceWallet?.address);
+    const runId = createLogicalRunId();
+    const runtimeFlow = input.mode === "execute"
+        ? "cast_execute"
+        : input.mode === "dry-run"
+            ? "cast_dry_run"
+            : "simulate";
+    const advisorSkillsDirs = resolveAdvisorSkillsDirs(input.options.advisorSkillsDir) ?? [];
+    const sourceOnAdvisory = await resolveAdvisoryHandler(input.sourceSpell.id, {
+        advisoryPi: input.options.advisoryPi,
+        advisoryReplay: input.options.advisoryReplay,
+        advisoryProvider: input.options.advisoryProvider,
+        advisoryModel: input.options.advisoryModel,
+        advisoryThinking: input.options.advisoryThinking,
+        advisoryTools: input.options.advisoryTools,
+        advisoryTraceVerbose: input.options.advisoryTraceVerbose,
+        advisoryTraceLogger: input.options.json ? undefined : console.log,
+        advisorSkillsDirs,
+        stateDir: input.options.stateDir,
+        noState: input.noState,
+        agentDir: input.options.piAgentDir,
+        cwd: process.cwd(),
+    });
+    const destinationOnAdvisory = await resolveAdvisoryHandler(destinationSpell.id, {
+        advisoryPi: input.options.advisoryPi,
+        advisoryReplay: input.options.advisoryReplay,
+        advisoryProvider: input.options.advisoryProvider,
+        advisoryModel: input.options.advisoryModel,
+        advisoryThinking: input.options.advisoryThinking,
+        advisoryTools: input.options.advisoryTools,
+        advisoryTraceVerbose: input.options.advisoryTraceVerbose,
+        advisoryTraceLogger: input.options.json ? undefined : console.log,
+        advisorSkillsDirs,
+        stateDir: input.options.stateDir,
+        noState: input.noState,
+        agentDir: input.options.piAgentDir,
+        cwd: process.cwd(),
+    });
+    const advisoryEventCallback = input.options.json
+        ? undefined
+        : createAdvisoryLiveTraceLogger(console.log, {
+            verbose: input.options.advisoryTraceVerbose,
+        });
+    const dbPath = input.options.stateDir ? join(input.options.stateDir, "grimoire.db") : undefined;
+    let store;
+    if (!input.noState) {
+        try {
+            store = new SqliteStateStore({ dbPath });
+        }
+        catch (error) {
+            if (isMissingNodeSqliteBackend(error)) {
+                console.log(chalk.yellow("State persistence unavailable in Node (missing better-sqlite3). Continuing without persisted state."));
+            }
+            else {
+                throw error;
+            }
+        }
+    }
+    let sourceState = store ? ((await store.load(input.sourceSpell.id)) ?? {}) : {};
+    let destinationState = store ? ((await store.load(destinationSpell.id)) ?? {}) : {};
+    const lifecycleEvents = [];
+    const manifest = {
+        schema_version: "grimoire.cross_chain.phase1.v1",
+        run_id: runId,
+        source_spell_path: input.sourceSpellPath,
+        destination_spell_path: destinationSpellPath,
+        source_spell_id: input.sourceSpell.id,
+        destination_spell_id: destinationSpell.id,
+        source_chain_id: input.sourceChainId,
+        destination_chain_id: destinationChainId,
+        mode: input.mode,
+        watch: input.options.watch === true,
+        handoff_timeout_sec: handoffTimeoutSec,
+        poll_interval_sec: pollIntervalSec,
+        rpc_by_chain: {
+            [input.sourceChainId]: sourceRpcUrl,
+            [destinationChainId]: destinationRpcUrl,
+        },
+        params: input.params,
+        vault,
+        morpho_market_ids: morphoMarketIds,
+    };
+    const gasMultiplier = input.options.gasMultiplier
+        ? Number.parseFloat(input.options.gasMultiplier)
+        : 1.1;
+    const confirmCallback = input.options.skipConfirm || isTestnet(input.sourceChainId)
+        ? async () => true
+        : async (message) => {
+            console.log(message);
+            return await confirmPrompt(chalk.yellow("Proceed? (yes/no): "));
+        };
+    spinner.text = "Running source/destination orchestration...";
+    const orchestration = await orchestrateCrossChain({
+        runId,
+        sourceSpellId: input.sourceSpell.id,
+        destinationSpellId: destinationSpell.id,
+        sourceChainId: input.sourceChainId,
+        destinationChainId,
+        vault: vault,
+        sourceParams: input.params,
+        destinationParams: input.params,
+        mode: input.mode,
+        watch: input.options.watch === true,
+        handoffTimeoutSec,
+        pollIntervalSec,
+        executeSource: async () => {
+            const result = await execute({
+                spell: input.sourceSpell,
+                runId,
+                vault: vault,
+                chain: input.sourceChainId,
+                params: input.params,
+                persistentState: sourceState,
+                simulate: input.mode === "simulate",
+                executionMode: input.mode === "simulate" ? undefined : input.mode,
+                wallet: input.mode === "execute" ? sourceWallet : undefined,
+                provider: sourceProvider,
+                gasMultiplier,
+                confirmCallback,
+                skipTestnetConfirmation: input.options.skipConfirm ?? false,
+                adapters: configuredAdapters,
+                advisorSkillsDirs: advisorSkillsDirs.length > 0 ? advisorSkillsDirs : undefined,
+                onAdvisory: sourceOnAdvisory,
+                eventCallback: advisoryEventCallback,
+                warningCallback: (message) => console.log(chalk.yellow(`Warning: ${message}`)),
+                crossChain: {
+                    enabled: true,
+                    runId,
+                    trackId: "source",
+                    role: "source",
+                    morphoMarketIds,
+                },
+            });
+            sourceState = result.finalState;
+            return result;
+        },
+        executeDestination: async (params) => {
+            const result = await execute({
+                spell: destinationSpell,
+                runId,
+                vault: vault,
+                chain: destinationChainId,
+                params,
+                persistentState: destinationState,
+                simulate: input.mode === "simulate",
+                executionMode: input.mode === "simulate" ? undefined : input.mode,
+                wallet: input.mode === "execute" ? destinationWallet : undefined,
+                provider: destinationProvider,
+                gasMultiplier,
+                confirmCallback,
+                skipTestnetConfirmation: input.options.skipConfirm ?? false,
+                adapters: configuredAdapters,
+                advisorSkillsDirs: advisorSkillsDirs.length > 0 ? advisorSkillsDirs : undefined,
+                onAdvisory: destinationOnAdvisory,
+                eventCallback: advisoryEventCallback,
+                warningCallback: (message) => console.log(chalk.yellow(`Warning: ${message}`)),
+                crossChain: {
+                    enabled: true,
+                    runId,
+                    trackId: "destination",
+                    role: "destination",
+                    morphoMarketIds,
+                },
+            });
+            destinationState = result.finalState;
+            return result;
+        },
+        resolveHandoffStatus: async (handoff) => {
+            const across = configuredAdapters.find((adapter) => adapter.meta.name === "across");
+            if (!across) {
+                return { status: "pending" };
+            }
+            const resolver = across.bridgeLifecycle?.resolveHandoffStatus ?? across.resolveHandoffStatus;
+            if (!resolver) {
+                return { status: "pending" };
+            }
+            return resolver({
+                handoffId: handoff.handoffId,
+                originChainId: handoff.originChainId,
+                destinationChainId: handoff.destinationChainId,
+                originTxHash: handoff.originTxHash,
+                reference: handoff.reference,
+                asset: handoff.asset,
+                submittedAmount: handoff.submittedAmount,
+                walletAddress: vault,
+            });
+        },
+        onLifecycleEvent: (event) => {
+            lifecycleEvents.push(event);
+        },
+    });
+    const crossChainReceipt = toCrossChainReceipt({
+        runId,
+        sourceSpellId: input.sourceSpell.id,
+        destinationSpellId: destinationSpell.id,
+        sourceChainId: input.sourceChainId,
+        destinationChainId,
+        tracks: orchestration.tracks,
+        handoffs: orchestration.handoffs,
+    });
+    const sourceResult = orchestration.sourceResult;
+    const destinationResult = orchestration.destinationResult;
+    if (sourceResult) {
+        sourceResult.crossChain = crossChainReceipt;
+    }
+    if (destinationResult) {
+        destinationResult.crossChain = crossChainReceipt;
+    }
+    if (orchestration.pending && !store) {
+        throw new Error("Cannot leave a run in waiting state without persistence. Disable --no-state.");
+    }
+    if (store) {
+        if (sourceResult) {
+            await store.save(input.sourceSpell.id, sourceResult.finalState);
+            const sourceProvenance = {
+                ...buildRuntimeProvenanceManifest({
+                    runtimeMode: runtimeFlow,
+                    chainId: input.sourceChainId,
+                    policy: input.dataPolicy,
+                    replay: input.replayResolution,
+                    params: input.params,
+                    blockNumber: await safeGetBlockNumber(sourceProvider),
+                    rpcUrl: sourceProvider.rpcUrl,
+                }),
+                cross_chain: manifest,
+            };
+            await store.addRun(input.sourceSpell.id, createRunRecord(sourceResult, sourceProvenance));
+            await store.saveLedger(input.sourceSpell.id, runId, appendLifecycleLedgerEntries(sourceResult.ledgerEvents, lifecycleEvents, runId, input.sourceSpell.id));
+        }
+        if (destinationResult) {
+            await store.save(destinationSpell.id, destinationResult.finalState);
+            const destinationProvenance = {
+                ...buildRuntimeProvenanceManifest({
+                    runtimeMode: runtimeFlow,
+                    chainId: destinationChainId,
+                    policy: input.dataPolicy,
+                    replay: input.replayResolution,
+                    params: input.params,
+                    blockNumber: await safeGetBlockNumber(destinationProvider),
+                    rpcUrl: destinationProvider.rpcUrl,
+                }),
+                cross_chain: manifest,
+            };
+            await store.addRun(destinationSpell.id, createRunRecord(destinationResult, destinationProvenance));
+            await store.saveLedger(destinationSpell.id, runId, destinationResult.ledgerEvents);
+        }
+        await persistCrossChainState(store, {
+            runId,
+            tracks: orchestration.tracks,
+            handoffs: orchestration.handoffs,
+            sourceSpellId: input.sourceSpell.id,
+            destinationSpellId: destinationSpell.id,
+            sourceResult,
+            destinationResult,
+        });
+    }
+    spinner.stop();
+    const mergedResult = destinationResult ?? sourceResult;
+    if (!mergedResult) {
+        throw new Error("Cross-chain orchestration returned no execution results.");
+    }
+    if (input.options.json) {
+        console.log(stringifyJson({
+            success: orchestration.success,
+            pending: orchestration.pending,
+            runId,
+            crossChain: crossChainReceipt,
+            source: sourceResult
+                ? {
+                    success: sourceResult.success,
+                    error: sourceResult.structuredError,
+                    receipt: sourceResult.receipt,
+                }
+                : undefined,
+            destination: destinationResult
+                ? {
+                    success: destinationResult.success,
+                    error: destinationResult.structuredError,
+                    receipt: destinationResult.receipt,
+                }
+                : undefined,
+        }));
+    }
+    else {
+        console.log();
+        console.log(chalk.cyan("🔀 Cross-Chain Run:"));
+        console.log(`  ${chalk.dim("Run ID:")} ${runId}`);
+        console.log(`  ${chalk.dim("Source:")} ${input.sourceSpell.meta.name} (${input.sourceChainId}) -> ${chalk.dim("Destination:")} ${destinationSpell.meta.name} (${destinationChainId})`);
+        console.log(`  ${chalk.dim("Watch:")} ${input.options.watch === true ? "Yes" : "No"}`);
+        console.log(`  ${chalk.dim("Status:")} ${orchestration.pending ? chalk.yellow("waiting") : orchestration.success ? chalk.green("completed") : chalk.red("failed")}`);
+        for (const track of orchestration.tracks) {
+            const trackStatus = track.status === "completed"
+                ? chalk.green(track.status)
+                : track.status === "failed"
+                    ? chalk.red(track.status)
+                    : track.status === "waiting"
+                        ? chalk.yellow(track.status)
+                        : chalk.dim(track.status);
+            console.log(`  ${chalk.dim(`track:${track.trackId}`)} ${trackStatus} chain=${track.chainId} spell=${track.spellId}`);
+            if (track.error) {
+                console.log(`    ${chalk.red(track.error)}`);
+            }
+        }
+        for (const handoff of orchestration.handoffs) {
+            console.log(`  ${chalk.dim(`handoff:${handoff.handoffId}`)} ${handoff.status} submitted=${handoff.submittedAmount.toString()} settled=${handoff.settledAmount?.toString() ?? "n/a"}`);
+        }
+        if (orchestration.pending) {
+            console.log();
+            console.log(chalk.yellow("Run is waiting for handoff settlement. Resume with:"));
+            console.log(chalk.yellow(`  grimoire resume ${runId} --watch`));
+        }
+    }
+    if (!orchestration.success && !orchestration.pending) {
+        process.exit(1);
+    }
+}
 async function safeGetBlockNumber(provider) {
     try {
         return await provider.getBlockNumber();
@@ -373,6 +777,164 @@ async function safeGetBlockNumber(provider) {
         return undefined;
     }
 }
+async function resolveKeyConfig(options, spinner) {
+    const hasExplicitKey = !!(options.privateKey || options.mnemonic || options.keystore);
+    const hasEnvKey = !!(options.keyEnv && process.env[options.keyEnv]);
+    const hasDefaultKeystore = !hasExplicitKey && !hasEnvKey && existsSync(DEFAULT_KEYSTORE_PATH);
+    if (options.privateKey) {
+        return { type: "raw", source: options.privateKey };
+    }
+    if (options.keyEnv && process.env[options.keyEnv]) {
+        return { type: "env", source: options.keyEnv };
+    }
+    if (options.mnemonic) {
+        return { type: "mnemonic", source: options.mnemonic };
+    }
+    if (hasDefaultKeystore || options.keystore) {
+        const keystorePath = options.keystore ?? DEFAULT_KEYSTORE_PATH;
+        if (!existsSync(keystorePath)) {
+            spinner.fail(chalk.red(`No key provided and no keystore found at ${keystorePath}`));
+            console.log(chalk.dim("  Run 'grimoire wallet generate' to create one."));
+            process.exit(1);
+            throw new Error("unreachable");
+        }
+        const password = await resolveKeystorePassword(options, spinner);
+        if (!password) {
+            process.exit(1);
+            throw new Error("unreachable");
+        }
+        const keystoreJson = readFileSync(keystorePath, "utf-8");
+        return { type: "keystore", source: keystoreJson, password };
+    }
+    throw new Error("Execution mode requires wallet credentials, but no key source was provided");
+}
+function resolveVaultAddress(explicitVault, fallbackWalletAddress) {
+    if (explicitVault && explicitVault.length > 0) {
+        return explicitVault;
+    }
+    if (fallbackWalletAddress && fallbackWalletAddress.length > 0) {
+        return fallbackWalletAddress;
+    }
+    return "0x0000000000000000000000000000000000000000";
+}
+function parseRequiredNumber(value, flag) {
+    if (!value) {
+        throw new Error(`${flag} is required in cross-chain mode`);
+    }
+    const parsed = Number.parseInt(value, 10);
+    if (!Number.isFinite(parsed) || parsed <= 0) {
+        throw new Error(`${flag} must be a positive integer`);
+    }
+    return parsed;
+}
+function resolveRpcUrlFromOption(chainId, value) {
+    const parsed = parseRpcUrlMappings(value);
+    return resolveRpcUrlForChain(chainId, parsed);
+}
+function isMissingNodeSqliteBackend(error) {
+    if (!(error instanceof Error))
+        return false;
+    return error.message.includes("SqliteStateStore requires bun:sqlite (Bun) or better-sqlite3 (Node)");
+}
+function appendLifecycleLedgerEntries(entries, lifecycleEvents, runId, spellId) {
+    if (lifecycleEvents.length === 0) {
+        return entries;
+    }
+    const start = entries.length;
+    const extras = lifecycleEvents.map((event, index) => ({
+        id: `evt_cc_${String(start + index).padStart(3, "0")}`,
+        timestamp: Date.now(),
+        runId,
+        spellId,
+        event,
+    }));
+    return [...entries, ...extras];
+}
+async function persistCrossChainState(store, input) {
+    const nowIso = new Date().toISOString();
+    for (const track of input.tracks) {
+        const row = {
+            runId: input.runId,
+            trackId: track.trackId,
+            role: track.role,
+            spellId: track.spellId,
+            chainId: track.chainId,
+            status: track.status,
+            lastStepId: track.lastStepId,
+            error: track.error,
+            updatedAt: nowIso,
+        };
+        await store.upsertRunTrack(row);
+    }
+    for (const handoff of input.handoffs) {
+        const row = {
+            runId: input.runId,
+            handoffId: handoff.handoffId,
+            sourceTrackId: handoff.sourceTrackId,
+            destinationTrackId: handoff.destinationTrackId,
+            sourceStepId: handoff.sourceStepId,
+            originChainId: handoff.originChainId,
+            destinationChainId: handoff.destinationChainId,
+            asset: handoff.asset,
+            submittedAmount: handoff.submittedAmount.toString(),
+            settledAmount: handoff.settledAmount?.toString(),
+            status: handoff.status,
+            reference: handoff.reference,
+            originTxHash: handoff.originTxHash,
+            reason: handoff.reason,
+            createdAt: nowIso,
+            updatedAt: nowIso,
+            expiresAt: handoff.status === "expired" ? nowIso : undefined,
+        };
+        await store.upsertRunHandoff(row);
+    }
+    const sourceSteps = collectStepStatuses(input.sourceResult, "source", input.runId);
+    for (const step of sourceSteps) {
+        await store.upsertRunStepResult(step);
+    }
+    const destinationSteps = collectStepStatuses(input.destinationResult, "destination", input.runId);
+    for (const step of destinationSteps) {
+        await store.upsertRunStepResult(step);
+    }
+}
+function collectStepStatuses(result, trackId, runId) {
+    if (!result?.receipt) {
+        return [];
+    }
+    const nowIso = new Date().toISOString();
+    const byStep = new Map();
+    for (const planned of result.receipt.plannedActions) {
+        byStep.set(planned.stepId, {
+            runId,
+            trackId,
+            stepId: planned.stepId,
+            status: "pending",
+            idempotencyKey: `${runId}:${trackId}:${planned.stepId}`,
+            updatedAt: nowIso,
+        });
+    }
+    for (const tx of result.commit?.transactions ?? []) {
+        const existing = byStep.get(tx.stepId);
+        if (!existing)
+            continue;
+        existing.status = tx.success ? "confirmed" : "failed";
+        existing.reference = tx.hash;
+        existing.error = tx.error;
+    }
+    if (result.success && !result.commit) {
+        for (const step of byStep.values()) {
+            step.status = "confirmed";
+        }
+    }
+    if (!result.success) {
+        for (const step of byStep.values()) {
+            if (step.status !== "confirmed") {
+                step.status = "failed";
+            }
+        }
+    }
+    return [...byStep.values()];
+}
 async function resolveKeystorePassword(options, spinner) {
     const envName = options.passwordEnv ?? "KEYSTORE_PASSWORD";
     const envValue = process.env[envName];