zk-agent-cli 0.1.0-beta.5 → 0.1.0-beta.7

package/dist/index.js

@@ -74,10 +74,215 @@ function isAgentError(error) {
 }
 
 // ../agent-core/src/storage.ts
-import { createCipheriv, createDecipheriv, randomBytes } from "node:crypto";
+import { createCipheriv, createDecipheriv, randomBytes as randomBytes2 } from "node:crypto";
 import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
+
+// ../agent-session-protocol/src/constants.ts
+var PROTOCOL_VERSION = "zk-agent-session-v1";
+
+// ../agent-session-protocol/src/encoding.ts
+function bytesToHex(bytes) {
+  return Array.from(bytes).map((byte) => byte.toString(16).padStart(2, "0")).join("");
+}
+function hexToBytes(hex) {
+  if (hex.length % 2 !== 0) throw new Error("Invalid hex string");
+  const bytes = new Uint8Array(hex.length / 2);
+  for (let index = 0; index < bytes.length; index += 1) {
+    bytes[index] = Number.parseInt(hex.slice(index * 2, index * 2 + 2), 16);
+  }
+  return bytes;
+}
+function b64urlEncode(bytes) {
+  let binary = "";
+  for (const byte of bytes) binary += String.fromCharCode(byte);
+  return btoa(binary).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}
+function b64urlDecode(value) {
+  const normalized = value.replace(/-/g, "+").replace(/_/g, "/");
+  const padding = normalized.length % 4 === 0 ? "" : "=".repeat(4 - normalized.length % 4);
+  const binary = atob(normalized + padding);
+  const bytes = new Uint8Array(binary.length);
+  for (let index = 0; index < binary.length; index += 1) {
+    bytes[index] = binary.charCodeAt(index);
+  }
+  return bytes;
+}
+
+// ../agent-session-protocol/src/crypto.ts
+import { xchacha20poly1305 } from "@noble/ciphers/chacha";
+import { x25519 } from "@noble/curves/ed25519";
+import { secp256k1 } from "@noble/curves/secp256k1";
+import { hkdf } from "@noble/hashes/hkdf";
+import { sha256 } from "@noble/hashes/sha2";
+import { keccak_256 } from "@noble/hashes/sha3";
+import { randomBytes } from "@noble/hashes/utils";
+function deriveEthereumAddressFromPrivateKey(privateKeyHex) {
+  const normalized = privateKeyHex.startsWith("0x") ? privateKeyHex.slice(2) : privateKeyHex;
+  if (!/^[0-9a-fA-F]{64}$/.test(normalized)) {
+    throw new Error("sessionPrivateKey must be a 32-byte hex string");
+  }
+  const publicKey = secp256k1.getPublicKey(hexToBytes(normalized), false);
+  const digest = keccak_256(publicKey.slice(1));
+  return `0x${bytesToHex(digest.slice(-20))}`;
+}
+function generateX25519Keypair() {
+  const secretKey = randomBytes(32);
+  const publicKey = x25519.getPublicKey(secretKey);
+  return { secretKey, publicKey };
+}
+function computeCodeHash(requestId, code) {
+  if (!requestId) throw new Error("requestId must not be empty");
+  return sha256(new TextEncoder().encode(requestId + code));
+}
+function deriveEncryptionKey(sharedSecret, code, cliPublicKeyHex, walletPublicKeyHex) {
+  const salt = sha256(new TextEncoder().encode(code));
+  const info = new TextEncoder().encode(cliPublicKeyHex + walletPublicKeyHex + PROTOCOL_VERSION);
+  return hkdf(sha256, sharedSecret, salt, info, 32);
+}
+function decryptSession(encrypted, cliSecretKey, code, requestId) {
+  if (!requestId) throw new Error("requestId must not be empty");
+  const cliPublicKey = x25519.getPublicKey(cliSecretKey);
+  const walletPublicKey = hexToBytes(encrypted.wallet_pk_hex);
+  const sharedSecret = x25519.getSharedSecret(cliSecretKey, walletPublicKey);
+  const cliPublicKeyHex = bytesToHex(cliPublicKey);
+  const encryptionKey = deriveEncryptionKey(
+    sharedSecret,
+    code,
+    cliPublicKeyHex,
+    encrypted.wallet_pk_hex
+  );
+  const expectedHash = bytesToHex(computeCodeHash(requestId, code));
+  if (expectedHash !== encrypted.code_hash_hex) {
+    throw new Error("Invalid code: hash mismatch");
+  }
+  const nonce = hexToBytes(encrypted.nonce_hex);
+  const aad = new Uint8Array([...cliPublicKey, ...walletPublicKey]);
+  const ciphertext = b64urlDecode(encrypted.ciphertext_b64url);
+  const cipher = xchacha20poly1305(encryptionKey, nonce, aad);
+  const plaintext = cipher.decrypt(ciphertext);
+  return JSON.parse(new TextDecoder().decode(plaintext));
+}
+
+// ../agent-session-protocol/src/connector.ts
+var textEncoder = new TextEncoder();
+var textDecoder = new TextDecoder();
+function isAddress(value) {
+  return /^0x[a-fA-F0-9]{40}$/.test(value);
+}
+function encodeSessionApprovalRequest(request) {
+  return b64urlEncode(textEncoder.encode(JSON.stringify(request)));
+}
+function buildApprovedSessionPayload(input) {
+  if (!isAddress(input.walletAddress)) throw new Error("walletAddress must be a valid address");
+  const derivedOwnerAddress = input.sessionPrivateKey ? deriveEthereumAddressFromPrivateKey(input.sessionPrivateKey) : void 0;
+  const ownerAddress = input.ownerAddress || derivedOwnerAddress;
+  if (ownerAddress && !isAddress(ownerAddress)) {
+    throw new Error("ownerAddress must be a valid address");
+  }
+  if (input.sessionAddress && !isAddress(input.sessionAddress)) {
+    throw new Error("sessionAddress must be a valid address");
+  }
+  if (input.sessionPrivateKey && !/^0x[0-9a-fA-F]{64}$/.test(input.sessionPrivateKey)) {
+    throw new Error("sessionPrivateKey must be a 32-byte hex string");
+  }
+  if (input.validatorAddress && !isAddress(input.validatorAddress)) {
+    throw new Error("validatorAddress must be a valid address");
+  }
+  if (input.paymasterAddress && !isAddress(input.paymasterAddress)) {
+    throw new Error("paymasterAddress must be a valid address");
+  }
+  if (input.paymasterToken && !isAddress(input.paymasterToken)) {
+    throw new Error("paymasterToken must be a valid address");
+  }
+  if (input.request.requestedAccountKind === "smart-account" && !ownerAddress) {
+    throw new Error(
+      "Smart-account approval requires ownerAddress or a sessionPrivateKey that can be used to derive it"
+    );
+  }
+  const signerType = input.signerType || (input.sessionPrivateKey ? "local" : "connector");
+  return {
+    version: 1,
+    provider: input.request.provider,
+    chain: input.request.chain,
+    chainId: input.request.chainId,
+    walletAddress: input.walletAddress,
+    account: {
+      kind: input.request.requestedAccountKind,
+      address: input.walletAddress,
+      ownerAddress,
+      sessionAddress: input.sessionAddress,
+      validatorAddress: input.validatorAddress,
+      signerType
+    },
+    sessionScope: input.request.requestedSessionScope,
+    capabilities: input.request.requestedCapabilities,
+    sessionExpiresAt: input.request.expiresAt,
+    paymaster: {
+      mode: input.request.requestedPaymasterMode,
+      address: input.paymasterAddress || null,
+      token: input.paymasterToken
+    },
+    sessionPublicKey: input.request.sessionPublicKey,
+    sessionPrivateKey: input.sessionPrivateKey,
+    sessionAddress: input.sessionAddress,
+    permissions: input.request.policies,
+    connectorUrl: input.connectorUrl || input.request.connectorUrl,
+    connectorOrigin: input.connectorOrigin,
+    paymasterAddress: input.paymasterAddress || null,
+    metadata: input.metadata
+  };
+}
+
+// ../agent-core/src/wallet-session.ts
+function isHexPrivateKey(value) {
+  return /^0x[a-fA-F0-9]{64}$/.test(value);
+}
+function deriveLocalExecutionSignerAddress(privateKey) {
+  if (!privateKey || !isHexPrivateKey(privateKey)) return void 0;
+  try {
+    return deriveEthereumAddressFromPrivateKey(privateKey);
+  } catch {
+    return void 0;
+  }
+}
+function buildLocalExecutionAuthority(input) {
+  if (!input.privateKey) return void 0;
+  return {
+    privateKey: input.privateKey,
+    signerAddress: deriveLocalExecutionSignerAddress(input.privateKey),
+    signerType: input.signerType || "local",
+    source: input.source,
+    attachedAt: input.attachedAt
+  };
+}
+function resolveLocalExecutionPrivateKey(wallet) {
+  return wallet.localExecutionAuthority?.privateKey || wallet.sessionPayload?.sessionPrivateKey;
+}
+function migrateWalletSessionRecord(wallet) {
+  const legacyPrivateKey = wallet.sessionPayload?.sessionPrivateKey;
+  const existingAuthority = wallet.localExecutionAuthority;
+  if (!existingAuthority && !legacyPrivateKey) {
+    return wallet;
+  }
+  const privateKey = existingAuthority?.privateKey || legacyPrivateKey;
+  if (!privateKey) {
+    return wallet;
+  }
+  return {
+    ...wallet,
+    localExecutionAuthority: {
+      privateKey,
+      signerAddress: existingAuthority?.signerAddress || deriveLocalExecutionSignerAddress(privateKey),
+      signerType: existingAuthority?.signerType || wallet.sessionPayload?.account?.signerType || "local",
+      source: existingAuthority?.source || (legacyPrivateKey ? "legacy-session-payload" : void 0),
+      attachedAt: existingAuthority?.attachedAt || wallet.createdAt
+    }
+  };
+}
+
+// ../agent-core/src/storage.ts
 function normalizeOptionalPath(value) {
   const trimmed = value?.trim();
   return trimmed ? path.resolve(trimmed) : null;
@@ -126,13 +331,13 @@ function getEncryptionKey() {
   const storageDirectory = ensureStorageDir();
   const encryptionKeyFile = path.join(storageDirectory, ".encryption-key");
   if (fs.existsSync(encryptionKeyFile)) return fs.readFileSync(encryptionKeyFile);
-  const key = randomBytes(32);
+  const key = randomBytes2(32);
   fs.writeFileSync(encryptionKeyFile, key, { mode: 384 });
   return key;
 }
 function encrypt(plaintext) {
   const key = getEncryptionKey();
-  const iv = randomBytes(16);
+  const iv = randomBytes2(16);
   const cipher = createCipheriv("aes-256-gcm", key, iv);
   let encrypted = cipher.update(plaintext, "utf8", "hex");
   encrypted += cipher.final("hex");
@@ -181,12 +386,15 @@ async function loadProjectConfig() {
 }
 async function saveWalletSession(record) {
   const storageDirectory = ensureStorageDir();
-  writeEncryptedJson(path.join(storageDirectory, "wallets", `${record.walletName}.json`), record);
+  writeEncryptedJson(
+    path.join(storageDirectory, "wallets", `${record.walletName}.json`),
+    migrateWalletSessionRecord(record)
+  );
 }
 async function loadWalletSession(walletName) {
   const filePath = storagePath("wallets", `${walletName}.json`);
   if (!fs.existsSync(filePath)) return null;
-  return readEncryptedJson(filePath);
+  return migrateWalletSessionRecord(readEncryptedJson(filePath));
 }
 async function listWalletNames() {
   const storageDirectory = ensureStorageDir();
@@ -2225,22 +2433,33 @@ function buildWalletPreparationActions(input) {
   const { wallet, inspection, funding } = input;
   const exclude = new Set(input.excludeActionIds || []);
   const actions = [];
-  if (!exclude.has("reapprove") && !inspection.sessionPrivateKeyStored) {
+  const approvalReady = inspection.approvalReady ?? Boolean(wallet.sessionPayload);
+  const localExecutionReady = inspection.localExecutionKeyStored ?? inspection.sessionPrivateKeyStored;
+  if (!exclude.has("reapprove") && !approvalReady) {
     actions.push({
       id: "reapprove",
       priority: "required",
-      title: "Restore a writable local session",
-      reason: "No local session key is stored, so this wallet cannot execute local write actions yet.",
+      title: "Restore approved session metadata",
+      reason: localExecutionReady ? "A local execution signer is already present, but approved session metadata is missing or not usable yet." : "Approved session metadata is missing, so this wallet cannot execute local write actions yet.",
       command: `zk-agent wallet reapprove --name ${wallet.walletName} --await-local`
     });
   }
+  if (!exclude.has("attach-signer") && approvalReady && !localExecutionReady) {
+    actions.push({
+      id: "attach-signer",
+      priority: "required",
+      title: "Attach a local execution signer",
+      reason: "Approved session metadata exists, but no local execution signer is stored for write actions yet.",
+      command: `zk-agent wallet signer attach --name ${wallet.walletName} --private-key <hex>`
+    });
+  }
   if (!exclude.has("signer-mismatch") && inspection.signerMatchesStoredIdentity === false) {
     actions.push({
       id: "signer-mismatch",
       priority: "required",
       title: "Repair the signer/address mismatch",
       reason: "The stored local signer does not match the wallet identity currently recorded for this session.",
-      command: `zk-agent wallet reapprove --name ${wallet.walletName} --await-local`
+      command: `zk-agent wallet signer attach --name ${wallet.walletName} --private-key <hex>`
     });
   }
   if (!exclude.has("deploy") && inspection.accountKind === "smart-account" && inspection.deploymentStatus === "not-deployed") {
@@ -2784,7 +3003,7 @@ async function loadWorkflowRuntimeState(wallet, intent, provider4, protocol, toC
 }
 function manualBlockingActionIds(plan) {
   return plan.steps.filter(
-    (step) => step.kind === "prerequisite" && step.priority === "required" && (step.id === "reapprove" || step.id === "signer-mismatch" || step.id === "deploy")
+    (step) => step.kind === "prerequisite" && step.priority === "required" && (step.id === "reapprove" || step.id === "attach-signer" || step.id === "signer-mismatch" || step.id === "deploy")
   ).map((step) => step.id);
 }
 function buildWorkflowGoalCommand(goal, wallet) {
@@ -3120,7 +3339,7 @@ function mergeNotes2(...groups) {
 }
 function manualBlockingActionIds2(plan) {
   return plan.steps.filter(
-    (step) => step.kind === "prerequisite" && step.priority === "required" && (step.id === "reapprove" || step.id === "signer-mismatch" || step.id === "deploy")
+    (step) => step.kind === "prerequisite" && step.priority === "required" && (step.id === "reapprove" || step.id === "attach-signer" || step.id === "signer-mismatch" || step.id === "deploy")
   ).map((step) => step.id);
 }
 async function inspectWorkflowStatus(input, deps) {
@@ -4159,28 +4378,28 @@ function getL1ExplorerUrl(l1ChainId, txHash) {
       return void 0;
   }
 }
-function isHexPrivateKey(value) {
+function isHexPrivateKey2(value) {
   return /^0x[a-fA-F0-9]{64}$/.test(value);
 }
 function deriveSignerAddress(privateKey) {
-  if (!privateKey || !isHexPrivateKey(privateKey)) return void 0;
+  if (!privateKey || !isHexPrivateKey2(privateKey)) return void 0;
   return new Wallet(privateKey).address;
 }
 function requireWritableSession(wallet) {
-  const privateKey = wallet.sessionPayload?.sessionPrivateKey;
+  const privateKey = resolveLocalExecutionPrivateKey(wallet);
   if (!privateKey) {
     throw new AgentError(
       "WRITABLE_SESSION_REQUIRED",
-      "Writable local execution requires a stored sessionPrivateKey.",
+      "Writable local execution requires a stored local execution key.",
       {
         walletName: wallet.walletName
       }
     );
   }
-  if (!isHexPrivateKey(privateKey)) {
+  if (!isHexPrivateKey2(privateKey)) {
     throw new AgentError(
       "WRITABLE_SESSION_INVALID",
-      "Stored sessionPrivateKey is not a valid 32-byte hex key.",
+      "Stored local execution key is not a valid 32-byte hex key.",
       {
         walletName: wallet.walletName
       }
@@ -4193,7 +4412,7 @@ function resolveWritableSignerAddress(wallet, privateKey) {
   if (!derivedSignerAddress) {
     throw new AgentError(
       "WRITABLE_SESSION_INVALID",
-      "Stored sessionPrivateKey is not a valid 32-byte hex key.",
+      "Stored local execution key is not a valid 32-byte hex key.",
       {
         walletName: wallet.walletName
       }
@@ -4204,7 +4423,7 @@ function resolveWritableSignerAddress(wallet, privateKey) {
     if (derivedSignerAddress.toLowerCase() !== executionAddress.toLowerCase()) {
       throw new AgentError(
         "EOA_SIGNER_MISMATCH",
-        "Stored sessionPrivateKey does not match the EOA execution address.",
+        "Stored local execution key does not match the EOA execution address.",
         {
           walletName: wallet.walletName,
           executionAddress,
@@ -4228,7 +4447,7 @@ function resolveWritableSignerAddress(wallet, privateKey) {
     if (derivedSignerAddress.toLowerCase() !== ownerAddress.toLowerCase()) {
       throw new AgentError(
         "SMART_ACCOUNT_SIGNER_MISMATCH",
-        "Stored sessionPrivateKey does not match the smart-account ownerAddress.",
+        "Stored local execution key does not match the smart-account ownerAddress.",
         {
           walletName: wallet.walletName,
           ownerAddress,
@@ -4255,7 +4474,7 @@ async function buildSigner(wallet, provider4) {
     if (derivedSignerAddress && derivedSignerAddress.toLowerCase() !== executionAddress.toLowerCase()) {
       throw new AgentError(
         "EOA_SIGNER_MISMATCH",
-        "Stored sessionPrivateKey does not match the EOA execution address.",
+        "Stored local execution key does not match the EOA execution address.",
         {
           walletName: wallet.walletName,
           executionAddress,
@@ -4279,7 +4498,7 @@ async function buildSigner(wallet, provider4) {
     if (derivedSignerAddress && derivedSignerAddress.toLowerCase() !== ownerAddress.toLowerCase()) {
       throw new AgentError(
         "SMART_ACCOUNT_SIGNER_MISMATCH",
-        "Stored sessionPrivateKey does not match the smart-account ownerAddress.",
+        "Stored local execution key does not match the smart-account ownerAddress.",
         {
           walletName: wallet.walletName,
           ownerAddress,
@@ -6039,188 +6258,31 @@ var ZkSyncDefiProvider = class {
             cause: formatCause(error),
             finalizationStatus: pendingFailure.kind,
             reason: pendingFailure.reason,
-            note: pendingFailure.note,
-            retryable: true,
-            suggestedAction: pendingFailure.suggestedAction
-          }
-        );
-      }
-      const code = input.broadcast ? "WITHDRAW_FINALIZE_BROADCAST_FAILED" : "WITHDRAW_FINALIZE_PREVIEW_FAILED";
-      const message = input.broadcast ? "Failed to broadcast the L1 withdraw finalization transaction." : "Failed to derive withdraw finalization parameters from the L2 transaction.";
-      throw new AgentError(
-        code,
-        message,
-        {
-          chain: chain.key,
-          l1ChainId,
-          txHash,
-          index,
-          cause: formatCause(error)
-        }
-      );
-    }
-  }
-};
-
-// ../provider-zksync-wallet/src/provider.ts
-import { randomBytes as randomBytes3 } from "node:crypto";
-
-// ../agent-session-protocol/src/constants.ts
-var PROTOCOL_VERSION = "zk-agent-session-v1";
-
-// ../agent-session-protocol/src/encoding.ts
-function bytesToHex(bytes) {
-  return Array.from(bytes).map((byte) => byte.toString(16).padStart(2, "0")).join("");
-}
-function hexToBytes(hex) {
-  if (hex.length % 2 !== 0) throw new Error("Invalid hex string");
-  const bytes = new Uint8Array(hex.length / 2);
-  for (let index = 0; index < bytes.length; index += 1) {
-    bytes[index] = Number.parseInt(hex.slice(index * 2, index * 2 + 2), 16);
-  }
-  return bytes;
-}
-function b64urlEncode(bytes) {
-  let binary = "";
-  for (const byte of bytes) binary += String.fromCharCode(byte);
-  return btoa(binary).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
-}
-function b64urlDecode(value) {
-  const normalized = value.replace(/-/g, "+").replace(/_/g, "/");
-  const padding = normalized.length % 4 === 0 ? "" : "=".repeat(4 - normalized.length % 4);
-  const binary = atob(normalized + padding);
-  const bytes = new Uint8Array(binary.length);
-  for (let index = 0; index < binary.length; index += 1) {
-    bytes[index] = binary.charCodeAt(index);
-  }
-  return bytes;
-}
-
-// ../agent-session-protocol/src/crypto.ts
-import { xchacha20poly1305 } from "@noble/ciphers/chacha";
-import { x25519 } from "@noble/curves/ed25519";
-import { secp256k1 } from "@noble/curves/secp256k1";
-import { hkdf } from "@noble/hashes/hkdf";
-import { sha256 } from "@noble/hashes/sha2";
-import { keccak_256 } from "@noble/hashes/sha3";
-import { randomBytes as randomBytes2 } from "@noble/hashes/utils";
-function deriveEthereumAddressFromPrivateKey(privateKeyHex) {
-  const normalized = privateKeyHex.startsWith("0x") ? privateKeyHex.slice(2) : privateKeyHex;
-  if (!/^[0-9a-fA-F]{64}$/.test(normalized)) {
-    throw new Error("sessionPrivateKey must be a 32-byte hex string");
-  }
-  const publicKey = secp256k1.getPublicKey(hexToBytes(normalized), false);
-  const digest = keccak_256(publicKey.slice(1));
-  return `0x${bytesToHex(digest.slice(-20))}`;
-}
-function generateX25519Keypair() {
-  const secretKey = randomBytes2(32);
-  const publicKey = x25519.getPublicKey(secretKey);
-  return { secretKey, publicKey };
-}
-function computeCodeHash(requestId, code) {
-  if (!requestId) throw new Error("requestId must not be empty");
-  return sha256(new TextEncoder().encode(requestId + code));
-}
-function deriveEncryptionKey(sharedSecret, code, cliPublicKeyHex, walletPublicKeyHex) {
-  const salt = sha256(new TextEncoder().encode(code));
-  const info = new TextEncoder().encode(cliPublicKeyHex + walletPublicKeyHex + PROTOCOL_VERSION);
-  return hkdf(sha256, sharedSecret, salt, info, 32);
-}
-function decryptSession(encrypted, cliSecretKey, code, requestId) {
-  if (!requestId) throw new Error("requestId must not be empty");
-  const cliPublicKey = x25519.getPublicKey(cliSecretKey);
-  const walletPublicKey = hexToBytes(encrypted.wallet_pk_hex);
-  const sharedSecret = x25519.getSharedSecret(cliSecretKey, walletPublicKey);
-  const cliPublicKeyHex = bytesToHex(cliPublicKey);
-  const encryptionKey = deriveEncryptionKey(
-    sharedSecret,
-    code,
-    cliPublicKeyHex,
-    encrypted.wallet_pk_hex
-  );
-  const expectedHash = bytesToHex(computeCodeHash(requestId, code));
-  if (expectedHash !== encrypted.code_hash_hex) {
-    throw new Error("Invalid code: hash mismatch");
-  }
-  const nonce = hexToBytes(encrypted.nonce_hex);
-  const aad = new Uint8Array([...cliPublicKey, ...walletPublicKey]);
-  const ciphertext = b64urlDecode(encrypted.ciphertext_b64url);
-  const cipher = xchacha20poly1305(encryptionKey, nonce, aad);
-  const plaintext = cipher.decrypt(ciphertext);
-  return JSON.parse(new TextDecoder().decode(plaintext));
-}
-
-// ../agent-session-protocol/src/connector.ts
-var textEncoder = new TextEncoder();
-var textDecoder = new TextDecoder();
-function isAddress(value) {
-  return /^0x[a-fA-F0-9]{40}$/.test(value);
-}
-function encodeSessionApprovalRequest(request) {
-  return b64urlEncode(textEncoder.encode(JSON.stringify(request)));
-}
-function buildApprovedSessionPayload(input) {
-  if (!isAddress(input.walletAddress)) throw new Error("walletAddress must be a valid address");
-  const derivedOwnerAddress = input.sessionPrivateKey ? deriveEthereumAddressFromPrivateKey(input.sessionPrivateKey) : void 0;
-  const ownerAddress = input.ownerAddress || derivedOwnerAddress;
-  if (ownerAddress && !isAddress(ownerAddress)) {
-    throw new Error("ownerAddress must be a valid address");
-  }
-  if (input.sessionAddress && !isAddress(input.sessionAddress)) {
-    throw new Error("sessionAddress must be a valid address");
-  }
-  if (input.sessionPrivateKey && !/^0x[0-9a-fA-F]{64}$/.test(input.sessionPrivateKey)) {
-    throw new Error("sessionPrivateKey must be a 32-byte hex string");
-  }
-  if (input.validatorAddress && !isAddress(input.validatorAddress)) {
-    throw new Error("validatorAddress must be a valid address");
-  }
-  if (input.paymasterAddress && !isAddress(input.paymasterAddress)) {
-    throw new Error("paymasterAddress must be a valid address");
-  }
-  if (input.paymasterToken && !isAddress(input.paymasterToken)) {
-    throw new Error("paymasterToken must be a valid address");
-  }
-  if (input.request.requestedAccountKind === "smart-account" && !ownerAddress) {
-    throw new Error(
-      "Smart-account approval requires ownerAddress or a sessionPrivateKey that can be used to derive it"
-    );
+            note: pendingFailure.note,
+            retryable: true,
+            suggestedAction: pendingFailure.suggestedAction
+          }
+        );
+      }
+      const code = input.broadcast ? "WITHDRAW_FINALIZE_BROADCAST_FAILED" : "WITHDRAW_FINALIZE_PREVIEW_FAILED";
+      const message = input.broadcast ? "Failed to broadcast the L1 withdraw finalization transaction." : "Failed to derive withdraw finalization parameters from the L2 transaction.";
+      throw new AgentError(
+        code,
+        message,
+        {
+          chain: chain.key,
+          l1ChainId,
+          txHash,
+          index,
+          cause: formatCause(error)
+        }
+      );
+    }
   }
-  return {
-    version: 1,
-    provider: input.request.provider,
-    chain: input.request.chain,
-    chainId: input.request.chainId,
-    walletAddress: input.walletAddress,
-    account: {
-      kind: input.request.requestedAccountKind,
-      address: input.walletAddress,
-      ownerAddress,
-      sessionAddress: input.sessionAddress,
-      validatorAddress: input.validatorAddress,
-      signerType: input.signerType || "connector"
-    },
-    sessionScope: input.request.requestedSessionScope,
-    capabilities: input.request.requestedCapabilities,
-    sessionExpiresAt: input.request.expiresAt,
-    paymaster: {
-      mode: input.request.requestedPaymasterMode,
-      address: input.paymasterAddress || null,
-      token: input.paymasterToken
-    },
-    sessionPublicKey: input.request.sessionPublicKey,
-    sessionPrivateKey: input.sessionPrivateKey,
-    sessionAddress: input.sessionAddress,
-    permissions: input.request.policies,
-    connectorUrl: input.connectorUrl || input.request.connectorUrl,
-    connectorOrigin: input.connectorOrigin,
-    paymasterAddress: input.paymasterAddress || null,
-    metadata: input.metadata
-  };
-}
+};
 
 // ../provider-zksync-wallet/src/provider.ts
+import { randomBytes as randomBytes3 } from "node:crypto";
 import { ethers as ethers2 } from "ethers";
 import { ContractFactory, ECDSASmartAccount as ECDSASmartAccount2, Provider as Provider2, Wallet as Wallet2, utils as utils2 } from "zksync-ethers";
 
@@ -6251,7 +6313,7 @@ function isAddress2(value) {
 function isHexData(value) {
   return /^0x([a-fA-F0-9]{2})*$/.test(value);
 }
-function isHexPrivateKey2(value) {
+function isHexPrivateKey3(value) {
   return /^0x[a-fA-F0-9]{64}$/.test(value);
 }
 function padHex(value, length = 64) {
@@ -6428,6 +6490,8 @@ function buildInspectionResult(wallet, codeLength, derivedSignerAddress, blocker
     paymasterMode: wallet.paymasterMode,
     deploymentStatus,
     codeLength,
+    approvalReady: Boolean(wallet.sessionPayload),
+    localExecutionKeyStored: Boolean(resolveLocalExecutionPrivateKey(wallet)),
     sessionPrivateKeyStored: Boolean(wallet.sessionPayload?.sessionPrivateKey),
     derivedSignerAddress,
     signerMatchesStoredIdentity,
@@ -6837,7 +6901,7 @@ async function preparePaymasterTransaction(wallet, tx, paymaster) {
   }
 }
 function deriveSignerAddress2(privateKey) {
-  if (!privateKey || !isHexPrivateKey2(privateKey)) return void 0;
+  if (!privateKey || !isHexPrivateKey3(privateKey)) return void 0;
   return new Wallet2(privateKey).address;
 }
 function normalizeSalt(value) {
@@ -6897,7 +6961,7 @@ async function resolveSmartAccountDeploymentContext(input) {
   if (deployerAddress.toLowerCase() !== ownerAddress.toLowerCase()) {
     throw new AgentError(
       "SMART_ACCOUNT_SIGNER_MISMATCH",
-      "Stored sessionPrivateKey does not match the smart-account ownerAddress.",
+      "Stored local execution key does not match the smart-account ownerAddress.",
       {
         walletName: wallet.walletName,
         ownerAddress,
@@ -6994,7 +7058,7 @@ async function resolveSmartAccountDeploymentContext(input) {
 async function inspectWalletRecord(wallet) {
   const executionAddress = resolveExecutionAddress2(wallet);
   const ownerAddress = resolveOwnerAddress2(wallet);
-  const sessionPrivateKey = wallet.sessionPayload?.sessionPrivateKey;
+  const sessionPrivateKey = resolveLocalExecutionPrivateKey(wallet);
   const derivedSignerAddress = deriveSignerAddress2(sessionPrivateKey);
   const provider4 = getProvider(wallet.chain);
   const code = await provider4.getCode(executionAddress);
@@ -7006,14 +7070,14 @@ async function inspectWalletRecord(wallet) {
   }
   if (!sessionPrivateKey) {
     blockers.push(
-      "Writable local execution requires a stored sessionPrivateKey. Re-approve locally with --session-private-key or import a writable session."
+      "Writable local execution requires a stored local execution key. Attach one with wallet signer attach, re-approve locally with --session-private-key, or import a writable session."
     );
-  } else if (!isHexPrivateKey2(sessionPrivateKey)) {
-    blockers.push("Stored sessionPrivateKey is not a valid 32-byte hex key.");
+  } else if (!isHexPrivateKey3(sessionPrivateKey)) {
+    blockers.push("Stored local execution key is not a valid 32-byte hex key.");
   }
   if (wallet.accountKind === "eoa") {
     if (derivedSignerAddress && derivedSignerAddress.toLowerCase() !== executionAddress.toLowerCase()) {
-      blockers.push("Stored sessionPrivateKey does not match the EOA execution address.");
+      blockers.push("Stored local execution key does not match the EOA execution address.");
     }
     if (codeLength > 0) {
       notes.push("EOA wallet record points to an address with deployed bytecode.");
@@ -7024,7 +7088,7 @@ async function inspectWalletRecord(wallet) {
       blockers.push("Smart-account session is missing ownerAddress metadata.");
     }
     if (ownerAddress && derivedSignerAddress && derivedSignerAddress.toLowerCase() !== ownerAddress.toLowerCase()) {
-      blockers.push("Stored sessionPrivateKey does not match the smart-account ownerAddress.");
+      blockers.push("Stored local execution key does not match the smart-account ownerAddress.");
     }
     if (codeLength === 0) {
       blockers.push(
@@ -7050,18 +7114,18 @@ async function assertWalletReadyForWrite(wallet) {
       { inspection }
     );
   }
-  const sessionPrivateKey = wallet.sessionPayload?.sessionPrivateKey;
-  if (!sessionPrivateKey || !isHexPrivateKey2(sessionPrivateKey)) {
+  const sessionPrivateKey = resolveLocalExecutionPrivateKey(wallet);
+  if (!sessionPrivateKey || !isHexPrivateKey3(sessionPrivateKey)) {
     throw new AgentError(
       "WRITABLE_SESSION_REQUIRED",
-      "Writable local execution requires a valid stored sessionPrivateKey.",
+      "Writable local execution requires a valid stored local execution key.",
       { inspection }
     );
   }
   if (wallet.accountKind === "eoa") {
     throw new AgentError(
       "EOA_SIGNER_MISMATCH",
-      "Stored sessionPrivateKey does not match the EOA execution address.",
+      "Stored local execution key does not match the EOA execution address.",
       { inspection }
     );
   }
@@ -7075,7 +7139,7 @@ async function assertWalletReadyForWrite(wallet) {
   if (inspection.signerMatchesStoredIdentity === false) {
     throw new AgentError(
       "SMART_ACCOUNT_SIGNER_MISMATCH",
-      "Stored sessionPrivateKey does not match the smart-account ownerAddress.",
+      "Stored local execution key does not match the smart-account ownerAddress.",
       { inspection }
     );
   }
@@ -7096,14 +7160,14 @@ async function assertWalletReadyForWrite(wallet) {
   );
 }
 function requireWritableSession2(wallet) {
-  const privateKey = wallet.sessionPayload?.sessionPrivateKey;
+  const privateKey = resolveLocalExecutionPrivateKey(wallet);
   if (!privateKey) {
     throw new Error(
-      "Writable session requires sessionPrivateKey. Re-approve locally with --session-private-key or import a writable testnet session."
+      "Writable session requires a stored local execution key. Re-approve locally with --session-private-key or import a writable testnet session."
     );
   }
-  if (!isHexPrivateKey2(privateKey)) {
-    throw new Error("Stored sessionPrivateKey is not a valid 32-byte hex key");
+  if (!isHexPrivateKey3(privateKey)) {
+    throw new Error("Stored local execution key is not a valid 32-byte hex key");
   }
   return privateKey;
 }
@@ -7354,6 +7418,13 @@ var ZkSyncWalletProvider = class {
     }
     const chain = resolveChain(payload.chainId);
     const walletAddress = payload.account?.address || payload.walletAddress;
+    const createdAt = (/* @__PURE__ */ new Date()).toISOString();
+    const localExecutionAuthority = buildLocalExecutionAuthority({
+      privateKey: payload.sessionPrivateKey,
+      signerType: payload.account?.signerType,
+      source: payload.sessionPrivateKey ? payload.account?.signerType === "local" ? "explicit-local-approval" : "approved-payload" : void 0,
+      attachedAt: createdAt
+    });
     return {
       walletName,
       walletAddress,
@@ -7367,7 +7438,8 @@ var ZkSyncWalletProvider = class {
       sessionScope: payload.sessionScope || summarizeScope(chain.key, chain.chainId),
       capabilities: payload.capabilities,
       paymasterMode: resolvePaymasterMode(payload),
-      createdAt: (/* @__PURE__ */ new Date()).toISOString(),
+      createdAt,
+      localExecutionAuthority,
       sessionPayload: payload
     };
   }
@@ -7692,6 +7764,9 @@ function buildWalletListRecommendedCommand() {
 function buildWalletStatusRecommendedCommand(walletName) {
   return `zk-agent wallet status --name ${walletName}`;
 }
+function buildWalletSignerAttachRecommendedCommand(walletName, privateKeyRef = "<hex>") {
+  return `zk-agent wallet signer attach --name ${walletName} --private-key ${privateKeyRef}`;
+}
 function buildAssetsRecommendedCommand(walletName) {
   return `zk-agent assets --wallet ${walletName}`;
 }
@@ -7760,6 +7835,10 @@ function buildWorkflowListRecommendedCommand() {
 function buildWorkflowAutoRecommendedCommand(walletName) {
   return `zk-agent workflow auto --wallet ${walletName} --intent <intent> [goal flags] --create-checkpoint --execute-when-ready`;
 }
+function buildWorkflowPayRecommendedCommand(walletName, paymasterMode) {
+  const command = `zk-agent workflow pay --wallet ${walletName} --to <address> --amount <amount>`;
+  return appendPaymasterMode(command, paymasterMode);
+}
 function buildWorkflowShowRecommendedCommand(requestId) {
   return `zk-agent workflow show --request-id ${requestId}`;
 }
@@ -10330,7 +10409,10 @@ function buildNextHelpText() {
   return [
     "",
     "Use `next` as the product entrypoint:",
-    "  Fresh operator routing:",
+    "  Fresh local-first routing:",
+    "    zk-agent setup",
+    "    zk-agent next",
+    "    zk-agent wallet create --await-local",
     "    zk-agent next",
     "",
     "  Continue a stored workflow checkpoint:",
@@ -10339,6 +10421,9 @@ function buildNextHelpText() {
     "  Stay on the wallet layer only when you need wallet-specific remediation:",
     "    zk-agent wallet next --name main",
     "",
+    "  Switch to the hosted remote-approval path only when the browser is not colocated:",
+    "    zk-agent wallet --help",
+    "",
     "  Stay on the workflow layer only when you already have an explicit workflow or checkpoint:",
     "    zk-agent workflow next --request-id <id>"
   ].join("\n");
@@ -10505,11 +10590,15 @@ function createNextCommand(deps) {
       nativeSymbol: nativeBalance?.symbol,
       funding
     });
+    const workflowPay = buildWorkflowPayRecommendedCommand(
+      wallet.walletName,
+      paymasterMode
+    );
     const workflowAuto = appendPaymasterMode2(
       buildWorkflowAutoRecommendedCommand(wallet.walletName),
       paymasterMode
     );
-    const nextCommand = summary.recommendedCommand || workflowAuto;
+    const nextCommand = summary.recommendedCommand || workflowPay;
     const agentFollowup = buildAgentFollowup(agentProfile, {
       walletName: wallet.walletName,
       walletExists: true
@@ -10521,6 +10610,7 @@ function createNextCommand(deps) {
       discoverOwnedTokens: buildOwnedTokensRecommendedCommand(wallet.walletName),
       discoverTokens: buildTokensRecommendedCommand(wallet.chain),
       inspectToken: buildResolveTokenRecommendedCommand(wallet.chain),
+      workflowPay,
       workflowAuto,
       nextAction: nextCommand,
       inspectDefaults: buildDefaultsRecommendedCommand()
@@ -10530,7 +10620,7 @@ function createNextCommand(deps) {
         ...walletNextLines(summary),
         ...agentProfileLines(agentProfile),
         ...agentFollowupLines(agentFollowup),
-        ...summary.recommendedCommand ? [] : [["next", workflowAuto]],
+        ...summary.recommendedCommand ? [] : [["next", workflowPay]],
         ["discover assets", recommendedCommands.discoverAssets],
         ["discover owned tokens", recommendedCommands.discoverOwnedTokens],
         ["discover tokens", recommendedCommands.discoverTokens],
@@ -11745,21 +11835,155 @@ import { Command as Command8 } from "commander";
 // src/lib/relay.ts
 import { createServer } from "node:http";
 import fs7 from "node:fs";
-import path6 from "node:path";
+import path7 from "node:path";
 import { fileURLToPath as fileURLToPath3 } from "node:url";
+
+// src/lib/http.ts
+import { spawn } from "node:child_process";
+import { mkdtemp, readFile as readFile2, rm as rm2 } from "node:fs/promises";
+import os2 from "node:os";
+import path6 from "node:path";
+function isDnsResolutionFailure(error) {
+  if (!error || typeof error !== "object") {
+    return false;
+  }
+  const cause = "cause" in error ? error.cause : void 0;
+  if (!cause || typeof cause !== "object") {
+    return false;
+  }
+  const code = "code" in cause ? cause.code : void 0;
+  return code === "ENOTFOUND" || code === "EAI_AGAIN";
+}
+function isHttpUrl(value) {
+  return value.startsWith("http://") || value.startsWith("https://");
+}
+function parseCurlHeaders(rawHeaders) {
+  const blocks = rawHeaders.replace(/\r\n/g, "\n").split(/\n{2,}/).map((block) => block.trim()).filter((block) => block.startsWith("HTTP/"));
+  const lastBlock = blocks.at(-1);
+  if (!lastBlock) {
+    throw new Error("curl fallback did not emit an HTTP response header block.");
+  }
+  const [statusLine, ...headerLines] = lastBlock.split("\n");
+  const status = Number.parseInt(statusLine.split(/\s+/)[1] || "", 10);
+  if (!Number.isInteger(status)) {
+    throw new Error(`curl fallback emitted an invalid status line: ${statusLine}`);
+  }
+  const headers = new Headers();
+  for (const line of headerLines) {
+    const separator = line.indexOf(":");
+    if (separator <= 0) continue;
+    const key = line.slice(0, separator).trim();
+    const value = line.slice(separator + 1).trim();
+    if (key) {
+      headers.append(key, value);
+    }
+  }
+  return { status, headers };
+}
+async function runCurlRequest(url, options) {
+  const tempDir = await mkdtemp(path6.join(os2.tmpdir(), "zk-agent-http-"));
+  const headersPath = path6.join(tempDir, "headers.txt");
+  const bodyPath = path6.join(tempDir, "body.txt");
+  try {
+    const args = [
+      "--silent",
+      "--show-error",
+      "--output",
+      bodyPath,
+      "--dump-header",
+      headersPath,
+      "--request",
+      options.method || "GET"
+    ];
+    if (options.redirect === "follow") {
+      args.push("--location");
+    }
+    for (const [key, value] of Object.entries(options.headers || {})) {
+      args.push("--header", `${key}: ${value}`);
+    }
+    if (typeof options.body === "string") {
+      args.push("--data-raw", options.body);
+    }
+    args.push(url);
+    const child = spawn("curl", args, {
+      env: process.env,
+      stdio: ["ignore", "pipe", "pipe"]
+    });
+    let stdout = "";
+    let stderr = "";
+    child.stdout.setEncoding("utf8");
+    child.stderr.setEncoding("utf8");
+    child.stdout.on("data", (chunk) => {
+      stdout += chunk;
+    });
+    child.stderr.on("data", (chunk) => {
+      stderr += chunk;
+    });
+    const exitCode = await new Promise((resolve, reject) => {
+      child.once("error", reject);
+      child.once("close", resolve);
+    });
+    if (exitCode !== 0) {
+      throw new Error(stderr.trim() || stdout.trim() || `curl exited with code ${exitCode}`);
+    }
+    const [rawHeaders, body] = await Promise.all([
+      readFile2(headersPath, "utf8"),
+      readFile2(bodyPath, "utf8")
+    ]);
+    const { status, headers } = parseCurlHeaders(rawHeaders);
+    return {
+      ok: status >= 200 && status < 300,
+      status,
+      headers,
+      body
+    };
+  } finally {
+    await rm2(tempDir, { recursive: true, force: true });
+  }
+}
+async function fetchTextWithFallback(url, options = {}) {
+  try {
+    const response = await fetch(url, {
+      method: options.method,
+      headers: options.headers,
+      body: options.body,
+      redirect: options.redirect
+    });
+    return {
+      ok: response.ok,
+      status: response.status,
+      headers: response.headers,
+      body: await response.text()
+    };
+  } catch (error) {
+    if (!isHttpUrl(url) || !isDnsResolutionFailure(error)) {
+      throw error;
+    }
+    return await runCurlRequest(url, options);
+  }
+}
+async function fetchJsonWithFallback(url, options = {}) {
+  const response = await fetchTextWithFallback(url, options);
+  return {
+    ...response,
+    json: JSON.parse(response.body)
+  };
+}
+
+// src/lib/relay.ts
 var RELAY_BODY_LIMIT_BYTES = 1024 * 1024;
 var RELAY_SERVICE = "zk-agent-relay";
 var RELAY_PROTOCOL = "zk-agent-session-relay";
 var RELAY_SCHEMA_VERSION = 1;
 function relayDir() {
-  const directory = path6.join(storageDir(), "relay");
+  const directory = path7.join(storageDir(), "relay");
   if (!fs7.existsSync(directory)) {
     fs7.mkdirSync(directory, { recursive: true, mode: 448 });
   }
   return directory;
 }
 function relayRecordPath(requestId) {
-  return path6.join(relayDir(), `${requestId}.json`);
+  return path7.join(relayDir(), `${requestId}.json`);
 }
 function writeRelayRecord(record) {
   fs7.writeFileSync(relayRecordPath(record.request_id), JSON.stringify(record, null, 2), {
@@ -11824,28 +12048,31 @@ function readRequestBody(request, limitBytes = RELAY_BODY_LIMIT_BYTES) {
   });
 }
 function writeJson2(response, statusCode, payload) {
-  response.statusCode = statusCode;
-  response.setHeader("Content-Type", "application/json; charset=utf-8");
-  response.setHeader("Access-Control-Allow-Origin", "*");
-  response.setHeader("Access-Control-Allow-Methods", "GET, POST, OPTIONS");
-  response.setHeader("Access-Control-Allow-Headers", "Content-Type");
-  response.end(JSON.stringify(payload, null, 2));
+  writeBody(response, statusCode, "application/json; charset=utf-8", JSON.stringify(payload, null, 2), {
+    "Access-Control-Allow-Origin": "*",
+    "Access-Control-Allow-Methods": "GET, POST, OPTIONS",
+    "Access-Control-Allow-Headers": "Content-Type"
+  });
 }
-function writeText(response, statusCode, contentType, value) {
+function writeBody(response, statusCode, contentType, value, extraHeaders = {}) {
   response.statusCode = statusCode;
   response.setHeader("Content-Type", contentType);
+  response.setHeader("Content-Length", Buffer.isBuffer(value) ? String(value.byteLength) : String(Buffer.byteLength(value)));
+  for (const [key, headerValue] of Object.entries(extraHeaders)) {
+    response.setHeader(key, headerValue);
+  }
   response.end(value);
 }
 function resolveConnectorUiDistRoot() {
   const currentFile = fileURLToPath3(import.meta.url);
-  const currentDir2 = path6.dirname(currentFile);
+  const currentDir2 = path7.dirname(currentFile);
   const candidates = [
-    path6.resolve(currentDir2, "./connector-ui"),
-    path6.resolve(currentDir2, "../../../zk-connector-ui/dist"),
-    path6.resolve(currentDir2, "../../zk-connector-ui/dist")
+    path7.resolve(currentDir2, "./connector-ui"),
+    path7.resolve(currentDir2, "../../../zk-connector-ui/dist"),
+    path7.resolve(currentDir2, "../../zk-connector-ui/dist")
   ];
   for (const candidate of candidates) {
-    if (fs7.existsSync(path6.join(candidate, "index.html"))) {
+    if (fs7.existsSync(path7.join(candidate, "index.html"))) {
       return candidate;
     }
   }
@@ -11861,8 +12088,8 @@ function contentTypeFor(filePath) {
 function normalizeRelayBaseUrl(baseUrl) {
   return baseUrl.replace(/\/+$/, "");
 }
-function resolveRelayPublicBaseUrl(actualBaseUrl, publicOrigin) {
-  return publicOrigin?.trim() ? normalizeRelayBaseUrl(new URL(publicOrigin.trim()).toString()) : normalizeRelayBaseUrl(actualBaseUrl);
+function resolveRelayPublicBaseUrl(bindBaseUrl, publicOrigin) {
+  return publicOrigin?.trim() ? normalizeRelayBaseUrl(new URL(publicOrigin.trim()).toString()) : normalizeRelayBaseUrl(bindBaseUrl);
 }
 function relayCapabilities(connectorUiAvailable) {
   return [
@@ -11874,15 +12101,16 @@ function relayCapabilities(connectorUiAvailable) {
     ...connectorUiAvailable ? ["connector-ui"] : []
   ];
 }
-function relayHealthResponse(actualBaseUrl, publicBaseUrl, connectorUiAvailable) {
+function relayHealthResponse(bindBaseUrl, publicBaseUrl, connectorUiAvailable, publicOriginSource) {
   return {
     ok: true,
     service: RELAY_SERVICE,
     protocol: RELAY_PROTOCOL,
     schema_version: RELAY_SCHEMA_VERSION,
     relay_mode: "local-file",
-    origin: normalizeRelayBaseUrl(actualBaseUrl),
+    origin: normalizeRelayBaseUrl(bindBaseUrl),
     public_origin: normalizeRelayBaseUrl(publicBaseUrl),
+    public_origin_source: publicOriginSource,
     connector_ui_available: connectorUiAvailable,
     capabilities: relayCapabilities(connectorUiAvailable)
   };
@@ -11897,31 +12125,34 @@ function relayApprovalUrl(baseUrl, requestId) {
   return `${relayStatusUrl(baseUrl, requestId)}/approval`;
 }
 async function publishRelayRequest(baseUrl, body) {
-  const response = await fetch(`${normalizeRelayBaseUrl(baseUrl)}/api/requests`, {
-    method: "POST",
-    headers: {
-      "Content-Type": "application/json"
-    },
-    body: JSON.stringify(body)
-  });
+  const response = await fetchJsonWithFallback(
+    `${normalizeRelayBaseUrl(baseUrl)}/api/requests`,
+    {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json"
+      },
+      body: JSON.stringify(body)
+    }
+  );
   if (!response.ok) {
     throw new Error(`Relay publish failed with status ${response.status}`);
   }
-  return await response.json();
+  return response.json;
 }
 async function fetchRelayStatus(baseUrl, requestId) {
-  const response = await fetch(relayStatusUrl(baseUrl, requestId));
+  const response = await fetchJsonWithFallback(relayStatusUrl(baseUrl, requestId));
   if (!response.ok) {
     throw new Error(`Relay status fetch failed with status ${response.status}`);
   }
-  return await response.json();
+  return response.json;
 }
 async function fetchRelayHealth(baseUrl) {
-  const response = await fetch(`${normalizeRelayBaseUrl(baseUrl)}/health`);
+  const response = await fetchJsonWithFallback(`${normalizeRelayBaseUrl(baseUrl)}/health`);
   if (!response.ok) {
     throw new Error(`Relay health fetch failed with status ${response.status}`);
   }
-  return await response.json();
+  return response.json;
 }
 function sleep(ms) {
   return new Promise((resolve) => {
@@ -11946,21 +12177,22 @@ async function waitForRelayApprovalReady(baseUrl, requestId, options) {
   );
 }
 async function fetchRelayApproval(baseUrl, requestId) {
-  const response = await fetch(relayApprovalUrl(baseUrl, requestId));
+  const response = await fetchJsonWithFallback(relayApprovalUrl(baseUrl, requestId));
   if (!response.ok) {
     throw new Error(`Relay approval fetch failed with status ${response.status}`);
   }
-  return await response.json();
+  return response.json;
 }
 async function startRelayServer(options) {
   const uiDistRoot = resolveConnectorUiDistRoot();
+  let bindBaseUrl = "";
+  const publicOriginSource = options.publicOrigin?.trim() ? "configured" : "bind-origin-default";
   const server = createServer(async (request, response) => {
     try {
-      const requestUrl = new URL(request.url || "/", `http://${request.headers.host || "localhost"}`);
+      const requestUrl = new URL(request.url || "/", "http://localhost");
       const pathname = requestUrl.pathname;
       const method = request.method || "GET";
-      const actualBaseUrl = `${requestUrl.protocol}//${requestUrl.host}`;
-      const publicBaseUrl = resolveRelayPublicBaseUrl(actualBaseUrl, options.publicOrigin);
+      const publicBaseUrl = resolveRelayPublicBaseUrl(bindBaseUrl, options.publicOrigin);
       if (method === "OPTIONS") {
         writeJson2(response, 204, {});
         return;
@@ -11969,7 +12201,12 @@ async function startRelayServer(options) {
         writeJson2(
           response,
           200,
-          relayHealthResponse(actualBaseUrl, publicBaseUrl, Boolean(uiDistRoot))
+          relayHealthResponse(
+            bindBaseUrl,
+            publicBaseUrl,
+            Boolean(uiDistRoot),
+            publicOriginSource
+          )
         );
         return;
       }
@@ -12038,18 +12275,18 @@ async function startRelayServer(options) {
       }
       if (method === "GET" && uiDistRoot) {
         const relativePath = pathname === "/" ? "/index.html" : pathname;
-        const filePath = path6.resolve(uiDistRoot, `.${relativePath}`);
+        const filePath = path7.resolve(uiDistRoot, `.${relativePath}`);
         if (!filePath.startsWith(uiDistRoot)) {
           writeJson2(response, 403, { error: "Forbidden path" });
           return;
         }
         if (fs7.existsSync(filePath) && fs7.statSync(filePath).isFile()) {
-          writeText(response, 200, contentTypeFor(filePath), fs7.readFileSync(filePath, "utf8"));
+          writeBody(response, 200, contentTypeFor(filePath), fs7.readFileSync(filePath));
           return;
         }
-        const indexPath = path6.join(uiDistRoot, "index.html");
+        const indexPath = path7.join(uiDistRoot, "index.html");
         if (fs7.existsSync(indexPath)) {
-          writeText(response, 200, "text/html; charset=utf-8", fs7.readFileSync(indexPath, "utf8"));
+          writeBody(response, 200, "text/html; charset=utf-8", fs7.readFileSync(indexPath));
           return;
         }
       }
@@ -12074,9 +12311,10 @@ async function startRelayServer(options) {
       });
     });
   });
+  bindBaseUrl = `http://${address.address}:${address.port}`;
   return {
     connectorUiAvailable: Boolean(uiDistRoot),
-    origin: `http://${address.address}:${address.port}`,
+    origin: bindBaseUrl,
     port: address.port,
     close: async () => await new Promise((resolve, reject) => {
       server.close((error) => {
@@ -12093,8 +12331,14 @@ async function startRelayServer(options) {
 // src/commands/relay.ts
 function buildRelayServeRecommendedCommands(relayUrl) {
   return {
-    createWallet: `zk-agent wallet create --relay-url ${relayUrl}`,
-    reapproveWallet: `zk-agent wallet reapprove --name main --relay-url ${relayUrl}`
+    createWallet: `zk-agent wallet create --relay-url ${relayUrl} --wait-relay --prompt-code`,
+    reapproveWallet: `zk-agent wallet reapprove --name main --relay-url ${relayUrl} --wait-relay --prompt-code`
+  };
+}
+function buildAdvertisedRelayBases(publicOrigin) {
+  return {
+    shareLinkBaseUrl: `${publicOrigin}/r`,
+    statusApiBaseUrl: `${publicOrigin}/api/requests`
   };
 }
 function isRecord3(value) {
@@ -12110,6 +12354,9 @@ function isRelayCapability(value) {
     "connector-ui"
   ].includes(String(value));
 }
+function isRelayPublicOriginSource(value) {
+  return value === "configured" || value === "bind-origin-default";
+}
 function asRelayHealthResponse(value) {
   if (!isRecord3(value)) return null;
   if (value.ok !== true) return null;
@@ -12119,6 +12366,9 @@ function asRelayHealthResponse(value) {
   if (value.relay_mode !== "local-file") return null;
   if (typeof value.origin !== "string") return null;
   if (typeof value.public_origin !== "string") return null;
+  if (typeof value.public_origin_source !== "undefined" && !isRelayPublicOriginSource(value.public_origin_source)) {
+    return null;
+  }
   if (typeof value.connector_ui_available !== "boolean") return null;
   if (!Array.isArray(value.capabilities) || !value.capabilities.every(isRelayCapability)) {
     return null;
@@ -12137,6 +12387,29 @@ function relayPublicOriginLooksLocal(origin) {
     return false;
   }
 }
+function normalizeComparableRelayUrl(value) {
+  try {
+    return new URL(value).toString().replace(/\/+$/, "");
+  } catch {
+    return null;
+  }
+}
+function relayUrlMatches(left, right) {
+  const normalizedLeft = normalizeComparableRelayUrl(left);
+  const normalizedRight = right ? normalizeComparableRelayUrl(right) : null;
+  if (normalizedLeft === null || normalizedRight === null) {
+    return null;
+  }
+  return normalizedLeft === normalizedRight;
+}
+function inferRelayPublicOriginSource(options) {
+  const normalizedOrigin = options.origin ? normalizeComparableRelayUrl(options.origin) : null;
+  const normalizedPublicOrigin = normalizeComparableRelayUrl(options.publicOrigin);
+  if (!normalizedOrigin || !normalizedPublicOrigin) {
+    return null;
+  }
+  return normalizedOrigin === normalizedPublicOrigin ? "bind-origin-default" : "configured";
+}
 function relayHostedReadinessNotes(options) {
   const notes = [];
   if (!options.compatible) {
@@ -12147,7 +12420,7 @@ function relayHostedReadinessNotes(options) {
   }
   if (relayPublicOriginLooksLocal(options.publicOrigin)) {
     notes.push(
-      "Relay compatibility is present, but the advertised public origin still points at a local-only address. Set --public-origin to the externally reachable URL before using this as a hosted approval path."
+      options.publicOriginSource === "bind-origin-default" ? "Relay compatibility is present, but the relay is still advertising its bind origin as the public origin. Set --public-origin to the externally reachable URL before using this as a hosted approval path." : "Relay compatibility is present, but the advertised public origin still points at a local-only address. Set --public-origin to the externally reachable URL before using this as a hosted approval path."
     );
   }
   if (options.connectorUiAvailable === false) {
@@ -12157,19 +12430,50 @@ function relayHostedReadinessNotes(options) {
   }
   return notes;
 }
+function relayOriginRelationshipNotes(options) {
+  const notes = [];
+  const relayUrlMatchesOrigin = relayUrlMatches(options.relayUrl, options.origin);
+  const relayUrlMatchesPublicOrigin = relayUrlMatches(options.relayUrl, options.publicOrigin);
+  if (relayUrlMatchesOrigin === false) {
+    notes.push(
+      "The inspected relay URL differs from the bind origin reported by /health. That is expected when you inspect a relay through a reverse proxy or tunnel instead of the local bind address."
+    );
+  }
+  if (relayUrlMatchesPublicOrigin === false) {
+    notes.push(
+      "The inspected relay URL differs from the advertised public origin. Share links and wallet approval commands will use the public origin, not the inspected relay URL."
+    );
+  }
+  return notes;
+}
 function buildRelayInspectPayload(relayUrl, rawHealth) {
   const health = asRelayHealthResponse(rawHealth);
   const fallbackPublicOrigin = isRecord3(rawHealth) && typeof rawHealth.public_origin === "string" ? rawHealth.public_origin : relayUrl;
   const publicOrigin = health?.public_origin || fallbackPublicOrigin;
+  const publicOriginSource = health?.public_origin_source || inferRelayPublicOriginSource({
+    origin: health?.origin || null,
+    publicOrigin
+  });
   const compatible = Boolean(health && hasCoreRelayCapabilities(health.capabilities));
   const connectorUiAvailable = health?.connector_ui_available ?? null;
+  const relayUrlMatchesOrigin = relayUrlMatches(relayUrl, health?.origin || null);
+  const relayUrlMatchesPublicOrigin = relayUrlMatches(relayUrl, publicOrigin);
   const publicOriginLooksLocal = relayPublicOriginLooksLocal(publicOrigin);
   const hostedShareRedirectReady = compatible && connectorUiAvailable === true && !publicOriginLooksLocal;
-  const notes = relayHostedReadinessNotes({
-    compatible,
-    publicOrigin,
-    connectorUiAvailable
-  });
+  const { shareLinkBaseUrl, statusApiBaseUrl } = buildAdvertisedRelayBases(publicOrigin);
+  const notes = [
+    ...relayHostedReadinessNotes({
+      compatible,
+      publicOrigin,
+      publicOriginSource,
+      connectorUiAvailable
+    }),
+    ...relayOriginRelationshipNotes({
+      relayUrl,
+      origin: health?.origin || null,
+      publicOrigin
+    })
+  ];
   return {
     ok: true,
     status: "relay-inspected",
@@ -12181,6 +12485,11 @@ function buildRelayInspectPayload(relayUrl, rawHealth) {
     relayMode: health?.relay_mode || null,
     origin: health?.origin || null,
     publicOrigin,
+    publicOriginSource,
+    shareLinkBaseUrl,
+    statusApiBaseUrl,
+    relayUrlMatchesOrigin,
+    relayUrlMatchesPublicOrigin,
     publicOriginLooksLocal,
     connectorUiAvailable,
     hostedShareRedirectReady,
@@ -12206,13 +12515,16 @@ function createRelayCommand() {
       publicOrigin: options.publicOrigin?.trim()
     });
     const publicOrigin = options.publicOrigin?.trim() || server.origin;
+    const publicOriginSource = options.publicOrigin?.trim() ? "configured" : "bind-origin-default";
     const publicOriginLooksLocal = relayPublicOriginLooksLocal(publicOrigin);
     const connectorUiAvailable = server.connectorUiAvailable;
     const hostedShareRedirectReady = connectorUiAvailable && !publicOriginLooksLocal;
+    const { shareLinkBaseUrl, statusApiBaseUrl } = buildAdvertisedRelayBases(publicOrigin);
     const recommendedCommands = buildRelayServeRecommendedCommands(publicOrigin);
     const notes = relayHostedReadinessNotes({
       compatible: true,
       publicOrigin,
+      publicOriginSource,
       connectorUiAvailable
     });
     const payload = {
@@ -12220,6 +12532,9 @@ function createRelayCommand() {
       status: "relay-serving",
       origin: server.origin,
       publicOrigin,
+      publicOriginSource,
+      shareLinkBaseUrl,
+      statusApiBaseUrl,
       publicOriginLooksLocal,
       port: server.port,
       healthUrl: `${server.origin}/health`,
@@ -12246,6 +12561,9 @@ function createRelayCommand() {
       if (publicOrigin !== server.origin) {
         humanLine("public origin", publicOrigin);
       }
+      humanLine("public origin source", publicOriginSource);
+      humanLine("share-link base", shareLinkBaseUrl);
+      humanLine("status api base", statusApiBaseUrl);
       humanLine("health", `${server.origin}/health`);
       humanLine("hosted ready", hostedShareRedirectReady ? "yes" : "no");
       if (connectorUiAvailable !== null) {
@@ -12297,6 +12615,20 @@ function createRelayCommand() {
     if (payload.publicOrigin) {
       humanLine("public origin", payload.publicOrigin);
     }
+    if (payload.publicOriginSource) {
+      humanLine("public origin source", payload.publicOriginSource);
+    }
+    humanLine("share-link base", payload.shareLinkBaseUrl);
+    humanLine("status api base", payload.statusApiBaseUrl);
+    if (payload.relayUrlMatchesOrigin !== null) {
+      humanLine("relay url matches origin", payload.relayUrlMatchesOrigin ? "yes" : "no");
+    }
+    if (payload.relayUrlMatchesPublicOrigin !== null) {
+      humanLine(
+        "relay url matches public origin",
+        payload.relayUrlMatchesPublicOrigin ? "yes" : "no"
+      );
+    }
     humanLine("public origin local", payload.publicOriginLooksLocal ? "yes" : "no");
     if (payload.connectorUiAvailable !== null) {
       humanLine("connector ui", payload.connectorUiAvailable ? "available" : "missing");
@@ -12312,10 +12644,9 @@ function createRelayCommand() {
       if (payload.recommendedCommands.reapproveWallet) {
         humanLine("reapprove wallet", payload.recommendedCommands.reapproveWallet);
       }
-    } else {
-      for (const note of payload.notes) {
-        humanLine("note", note);
-      }
+    }
+    for (const note of payload.notes) {
+      humanLine("note", note);
     }
   });
   return relay;
@@ -12328,12 +12659,12 @@ import { Command as Command9 } from "commander";
 
 // ../account-profiles/src/profiles.ts
 import fs8 from "node:fs";
-import path7 from "node:path";
+import path8 from "node:path";
 import { fileURLToPath as fileURLToPath4 } from "node:url";
 var PACKAGE_NAME = "@zk-agent/account-profiles";
 var PACKAGE_ROOT_FALLBACK = `<${PACKAGE_NAME} package root unavailable>`;
 function isExpectedPackageRoot(candidate) {
-  const manifestPath = path7.join(candidate, "package.json");
+  const manifestPath = path8.join(candidate, "package.json");
   if (!fs8.existsSync(manifestPath)) return false;
   try {
     const manifest = JSON.parse(fs8.readFileSync(manifestPath, "utf8"));
@@ -12343,19 +12674,19 @@ function isExpectedPackageRoot(candidate) {
   }
 }
 function resolvePackageRoot() {
-  const moduleRoot = path7.resolve(path7.dirname(fileURLToPath4(import.meta.url)), "..");
+  const moduleRoot = path8.resolve(path8.dirname(fileURLToPath4(import.meta.url)), "..");
   const cwd = process.cwd();
   const candidates = [
     process.env.ZK_AGENT_ACCOUNT_PROFILES_ROOT,
-    path7.join(moduleRoot, "dist", "builtin-account-profiles"),
+    path8.join(moduleRoot, "dist", "builtin-account-profiles"),
     moduleRoot,
-    path7.join(cwd, "packages", "account-profiles"),
-    path7.join(cwd, "account-profiles"),
+    path8.join(cwd, "packages", "account-profiles"),
+    path8.join(cwd, "account-profiles"),
     cwd
   ].filter((value) => typeof value === "string" && value.trim().length > 0);
   const seen = /* @__PURE__ */ new Set();
   for (const candidate of candidates) {
-    const normalized = path7.resolve(candidate);
+    const normalized = path8.resolve(candidate);
     if (seen.has(normalized)) continue;
     seen.add(normalized);
     if (isExpectedPackageRoot(normalized)) {
@@ -12427,11 +12758,11 @@ function missingArtifactError(profileId, artifactPath2) {
 }
 function contractPath(...segments) {
   const packageRoot = tryResolvePackageRoot();
-  return packageRoot ? path7.join(packageRoot, "contracts", ...segments) : path7.join(PACKAGE_ROOT_FALLBACK, "contracts", ...segments);
+  return packageRoot ? path8.join(packageRoot, "contracts", ...segments) : path8.join(PACKAGE_ROOT_FALLBACK, "contracts", ...segments);
 }
 function artifactPath(...segments) {
   const packageRoot = tryResolvePackageRoot();
-  return packageRoot ? path7.join(packageRoot, "artifacts", ...segments) : path7.join(PACKAGE_ROOT_FALLBACK, "artifacts", ...segments);
+  return packageRoot ? path8.join(packageRoot, "artifacts", ...segments) : path8.join(PACKAGE_ROOT_FALLBACK, "artifacts", ...segments);
 }
 function createDailySpendLimitProfile() {
   const resolvedArtifactPath = artifactPath("daily-spend-limit", "Account.json");
@@ -12853,6 +13184,7 @@ var WALLET_HELP_COMMAND_ORDER = [
   "rename",
   "remove",
   "request",
+  "signer",
   "paymaster",
   "smart-account"
 ];
@@ -12872,6 +13204,11 @@ var WALLET_SMART_ACCOUNT_HELP_COMMAND_ORDER = [
   "sed-lite",
   "daily-spend-limit"
 ];
+var WALLET_SIGNER_HELP_COMMAND_ORDER = [
+  "show",
+  "attach",
+  "remove"
+];
 function applyCommandOrder(command, orderedNames) {
   const order = new Map(orderedNames.map((name, index) => [name, index]));
   const sortedCommands = [...command.commands].sort((left, right) => {
@@ -12892,6 +13229,10 @@ function sanitizeSessionPayload(payload) {
 function stripSensitiveWalletRecord(wallet) {
   return {
     ...wallet,
+    localExecutionAuthority: wallet.localExecutionAuthority ? {
+      ...wallet.localExecutionAuthority,
+      privateKey: void 0
+    } : wallet.localExecutionAuthority,
     sessionPayload: wallet.sessionPayload ? {
       ...wallet.sessionPayload,
       sessionPrivateKey: void 0
@@ -12907,11 +13248,16 @@ function sanitizeWalletRecord(wallet) {
 function relayOutputAliases(relay) {
   const shareUrl = relay && "share_url" in relay ? relay.share_url : void 0;
   const statusUrl = relay && "status_url" in relay ? relay.status_url : void 0;
+  const approvalUrl = relay?.approval_url;
+  const shareLinkBaseUrl = shareUrl ? shareUrl.replace(/\/[^/]+$/, "") : approvalUrl ? approvalUrl.replace(/\/[^/]+$/, "") : void 0;
+  const statusApiBaseUrl = statusUrl ? statusUrl.replace(/\/[^/]+$/, "") : approvalUrl && relay?.request_id ? `${approvalUrl.replace(/\/r\/[^/]+$/, "")}/api/requests` : void 0;
   return {
     relayRequestId: relay?.request_id,
     relayShareUrl: shareUrl,
     relayStatusUrl: statusUrl,
-    relayApprovalUrl: relay?.approval_url
+    relayApprovalUrl: approvalUrl,
+    relayShareLinkBaseUrl: shareLinkBaseUrl,
+    relayStatusApiBaseUrl: statusApiBaseUrl
   };
 }
 function sanitizeWalletRequestRecord(request) {
@@ -12982,6 +13328,7 @@ function isRecord5(value) {
 function cloneWalletSessionRecord(wallet) {
   return {
     ...wallet,
+    localExecutionAuthority: wallet.localExecutionAuthority ? { ...wallet.localExecutionAuthority } : wallet.localExecutionAuthority,
     validationHookAddresses: wallet.validationHookAddresses ? [...wallet.validationHookAddresses] : wallet.validationHookAddresses,
     sessionScope: wallet.sessionScope ? {
       ...wallet.sessionScope,
@@ -13032,6 +13379,12 @@ function parseWalletExportRecord(value) {
   if (wallet.validatorAddress && !isAddress3(wallet.validatorAddress)) {
     throw new Error("Restore payload validatorAddress must be a valid 20-byte hex address.");
   }
+  if (wallet.localExecutionAuthority?.signerAddress && !isAddress3(wallet.localExecutionAuthority.signerAddress)) {
+    throw new Error("Restore payload localExecutionAuthority.signerAddress must be a valid 20-byte hex address.");
+  }
+  if (wallet.localExecutionAuthority?.privateKey && !/^0x[a-fA-F0-9]{64}$/.test(wallet.localExecutionAuthority.privateKey)) {
+    throw new Error("Restore payload localExecutionAuthority.privateKey must be a valid 32-byte hex string.");
+  }
   if (wallet.validationHookAddresses && wallet.validationHookAddresses.some((hookAddress) => !isAddress3(hookAddress))) {
     throw new Error("Restore payload validationHookAddresses must contain valid 20-byte hex addresses.");
   }
@@ -13064,7 +13417,7 @@ function parseWalletExportRecord(value) {
   }
   return {
     ...candidate,
-    wallet: cloneWalletSessionRecord(wallet)
+    wallet: migrateWalletSessionRecord(cloneWalletSessionRecord(wallet))
   };
 }
 function normalizeHexString2(value, label) {
@@ -13075,6 +13428,13 @@ function normalizeHexString2(value, label) {
   }
   return prefixed;
 }
+function normalizePrivateKey(value, label) {
+  const normalized = normalizeHexString2(value, label);
+  if (!/^0x[a-fA-F0-9]{64}$/.test(normalized)) {
+    throw new Error(`${label} must be a valid 32-byte hex string.`);
+  }
+  return normalized;
+}
 function parseArtifactInput(value) {
   const raw = parseJsonInput(value);
   if (!isRecord5(raw)) throw new Error("Artifact must be a JSON object");
@@ -13783,6 +14143,12 @@ function inspectionLines(inspection) {
       inspection.signerMatchesStoredIdentity ? "yes" : "no"
     ]);
   }
+  if (typeof inspection.approvalReady === "boolean") {
+    lines.push(["approval", inspection.approvalReady ? "present" : "missing"]);
+  }
+  if (typeof inspection.localExecutionKeyStored === "boolean") {
+    lines.push(["local signer", inspection.localExecutionKeyStored ? "stored" : "missing"]);
+  }
   lines.push(["session key", inspection.sessionPrivateKeyStored ? "stored" : "missing"]);
   if (inspection.paymasterMode) {
     lines.push(["paymaster", inspection.paymasterMode]);
@@ -13881,6 +14247,7 @@ function walletExportLines(wallet, bundle) {
 }
 function walletRestoreLines(wallet, restoredFrom, syncResult) {
   let nextCommand = buildWalletNextRecommendedCommand(wallet.walletName);
+  let afterNextCommandLabel;
   const lines = [
     ["wallet", wallet.walletName],
     ["address", wallet.walletAddress],
@@ -13891,12 +14258,15 @@ function walletRestoreLines(wallet, restoredFrom, syncResult) {
     ["source export", restoredFrom.exportedAt],
     ["sensitive data", restoredFrom.sensitiveDataIncluded ? "included in backup" : "not included in backup"]
   ];
-  if (!wallet.sessionPayload?.sessionPrivateKey) {
+  if (!resolveLocalExecutionPrivateKey(wallet)) {
+    const attachSignerCommand = buildWalletSignerAttachRecommendedCommand(wallet.walletName);
+    const reapproveCommand = buildWalletReapproveRecommendedCommand(wallet.walletName);
     lines.push([
       "note",
-      `No sessionPrivateKey was present in the backup. The restored wallet can be inspected and synced, but local write execution will stay blocked until you re-import or re-approve a writable session, for example: ${buildWalletReapproveRecommendedCommand(wallet.walletName)}`
+      wallet.sessionPayload ? `No local execution signer was present in the backup. The restored wallet can be inspected and synced, but local write execution will stay blocked until you attach a local signer or re-approve a writable session, for example: ${attachSignerCommand}` : `No local execution signer was present in the backup. The restored wallet can be inspected and synced, but local write execution will stay blocked until you re-import, attach a local signer, or re-approve a writable session, for example: ${reapproveCommand}`
     ]);
-    nextCommand = buildWalletReapproveRecommendedCommand(wallet.walletName);
+    nextCommand = wallet.sessionPayload ? attachSignerCommand : reapproveCommand;
+    afterNextCommandLabel = wallet.sessionPayload ? "after signer attach" : "after reapprove";
   }
   if (syncResult) {
     lines.push(["sync", "completed"]);
@@ -13920,7 +14290,10 @@ function walletRestoreLines(wallet, restoredFrom, syncResult) {
   }
   lines.push(["next", nextCommand]);
   if (nextCommand !== buildWalletNextRecommendedCommand(wallet.walletName)) {
-    lines.push(["after reapprove", buildWalletNextRecommendedCommand(wallet.walletName)]);
+    lines.push([
+      afterNextCommandLabel || "after reapprove",
+      buildWalletNextRecommendedCommand(wallet.walletName)
+    ]);
   }
   lines.push(["status command", buildWalletStatusRecommendedCommand(wallet.walletName)]);
   return lines;
@@ -13932,6 +14305,17 @@ function preserveExistingWalletMetadata(importedWallet, existingWallet) {
   if (existingWallet.chain !== importedWallet.chain || existingWallet.chainId !== importedWallet.chainId || existingWallet.walletAddress.toLowerCase() !== importedWallet.walletAddress.toLowerCase()) {
     return importedWallet;
   }
+  const sameAccountKind = existingWallet.accountKind === importedWallet.accountKind;
+  const sameSmartAccountOwner = existingWallet.accountKind !== "smart-account" || existingWallet.ownerAddress && importedWallet.ownerAddress && existingWallet.ownerAddress.toLowerCase() === importedWallet.ownerAddress.toLowerCase();
+  const existingSessionPrivateKey = resolveLocalExecutionPrivateKey(existingWallet);
+  const existingLocalExecutionAuthority = existingWallet.localExecutionAuthority || buildLocalExecutionAuthority({
+    privateKey: existingSessionPrivateKey,
+    signerType: existingWallet.sessionPayload?.account?.signerType,
+    source: existingSessionPrivateKey ? "legacy-session-payload" : void 0,
+    attachedAt: existingWallet.createdAt
+  });
+  const importedSessionPrivateKey = resolveLocalExecutionPrivateKey(importedWallet);
+  const shouldPreserveWritableSession = sameAccountKind && sameSmartAccountOwner && Boolean(existingSessionPrivateKey) && !importedSessionPrivateKey;
   const metadataUpdates = {};
   if (existingWallet.smartAccountProfileId) {
     const profileId = tryResolveBuiltinProfileId(existingWallet.smartAccountProfileId);
@@ -13948,7 +14332,13 @@ function preserveExistingWalletMetadata(importedWallet, existingWallet) {
   if (existingWallet.validatorAddress) {
     metadataUpdates.validatorAddress = existingWallet.validatorAddress;
   }
-  return applyWalletSyncMetadata(importedWallet, metadataUpdates);
+  const mergedWallet = shouldPreserveWritableSession && existingLocalExecutionAuthority ? {
+    ...importedWallet,
+    localExecutionAuthority: {
+      ...existingLocalExecutionAuthority
+    }
+  } : importedWallet;
+  return migrateWalletSessionRecord(applyWalletSyncMetadata(mergedWallet, metadataUpdates));
 }
 function linesForWriteResult2(result, nextCommand) {
   const lines = [
@@ -14042,23 +14432,85 @@ function buildWalletApprovalLines(status, requestId, walletRecord) {
   ];
 }
 function buildWalletFollowUpRecommendedCommands(walletRecord) {
+  const localExecutionReady = Boolean(resolveLocalExecutionPrivateKey(walletRecord));
+  const approvalReady = Boolean(walletRecord.sessionPayload);
   return {
     next: buildWalletNextRecommendedCommand(walletRecord.walletName),
     status: buildWalletStatusRecommendedCommand(walletRecord.walletName),
-    ...!walletRecord.sessionPayload?.sessionPrivateKey ? { reapprove: buildWalletReapproveRecommendedCommand(walletRecord.walletName) } : {}
+    ...!localExecutionReady && approvalReady ? {
+      attachSigner: buildWalletSignerAttachRecommendedCommand(walletRecord.walletName),
+      reapprove: buildWalletReapproveRecommendedCommand(walletRecord.walletName)
+    } : !localExecutionReady ? { reapprove: buildWalletReapproveRecommendedCommand(walletRecord.walletName) } : {}
+  };
+}
+function walletSignerSummary(walletRecord) {
+  const authority = walletRecord.localExecutionAuthority;
+  const localExecutionPrivateKey = resolveLocalExecutionPrivateKey(walletRecord);
+  return {
+    approvalReady: Boolean(walletRecord.sessionPayload),
+    localExecutionKeyStored: Boolean(localExecutionPrivateKey),
+    legacySessionKeyStored: Boolean(walletRecord.sessionPayload?.sessionPrivateKey),
+    signerAddress: authority?.signerAddress || deriveAddressFromPrivateKey(localExecutionPrivateKey),
+    signerType: authority?.signerType || walletRecord.sessionPayload?.account?.signerType,
+    source: authority?.source || (walletRecord.sessionPayload?.sessionPrivateKey ? "legacy-session-payload" : void 0),
+    attachedAt: authority?.attachedAt
+  };
+}
+function walletSignerLines(walletRecord) {
+  const signer = walletSignerSummary(walletRecord);
+  return [
+    ["wallet", walletRecord.walletName],
+    ["address", walletRecord.walletAddress],
+    ...displayOwnerAddress(walletRecord) ? [["owner", displayOwnerAddress(walletRecord)]] : [],
+    ["account", displayAccountKind(walletRecord)],
+    ["chain", `${walletRecord.chain} (${walletRecord.chainId})`],
+    ["approval", signer.approvalReady ? "present" : "missing"],
+    ["local signer", signer.localExecutionKeyStored ? "stored" : "missing"],
+    ["legacy payload mirror", signer.legacySessionKeyStored ? "present" : "missing"],
+    ...signer.signerType ? [["signer type", signer.signerType]] : [],
+    ...signer.signerAddress ? [["signer address", signer.signerAddress]] : [],
+    ...signer.source ? [["source", signer.source]] : [],
+    ...signer.attachedAt ? [["attached", signer.attachedAt]] : [],
+    ...walletFollowUpLines(walletRecord)
+  ];
+}
+function walletSignerAttachResult(walletRecord, note) {
+  return {
+    ok: true,
+    wallet: sanitizeWalletRecord(walletRecord),
+    signer: walletSignerSummary(walletRecord),
+    ...note ? { note } : {},
+    nextAction: buildWalletFollowUpNextAction(walletRecord),
+    recommendedCommands: buildWalletFollowUpRecommendedCommands(walletRecord)
   };
 }
+function normalizeSignerType(value) {
+  if (value === "local" || value === "connector" || value === "external") {
+    return value;
+  }
+  throw new Error(`Unsupported signer type: ${value}`);
+}
+function clearLegacySessionPrivateKey(payload) {
+  return payload ? {
+    ...payload,
+    sessionPrivateKey: void 0
+  } : payload;
+}
 function walletFollowUpLines(walletRecord) {
   const recommendedCommands = buildWalletFollowUpRecommendedCommands(walletRecord);
+  const nextCommand = recommendedCommands.attachSigner ?? recommendedCommands.reapprove ?? recommendedCommands.next;
   return [
-    ["next", recommendedCommands.reapprove ?? recommendedCommands.next],
-    ...recommendedCommands.reapprove ? [["after reapprove", recommendedCommands.next]] : [],
+    ["next", nextCommand],
+    ...recommendedCommands.attachSigner ? [
+      ["after signer attach", recommendedCommands.next],
+      ["or reapprove", recommendedCommands.reapprove]
+    ] : recommendedCommands.reapprove ? [["after reapprove", recommendedCommands.next]] : [],
     ["status command", recommendedCommands.status]
   ];
 }
 function buildWalletFollowUpNextAction(walletRecord) {
   const recommendedCommands = buildWalletFollowUpRecommendedCommands(walletRecord);
-  return recommendedCommands.reapprove ?? recommendedCommands.next;
+  return recommendedCommands.attachSigner ?? recommendedCommands.reapprove ?? recommendedCommands.next;
 }
 function buildPendingRequestRecommendedCommands(walletName, requestId, relayUrl, paymasterMode) {
   return {
@@ -14136,7 +14588,7 @@ async function createWalletReapprovalRequest(options) {
     chain: options.walletRecord.chain,
     connectorUrl,
     accountKind: displayAccountKind(options.walletRecord),
-    paymasterMode: displayPaymasterMode(options.walletRecord),
+    paymasterMode: options.paymasterMode || displayPaymasterMode(options.walletRecord),
     policies
   });
   await saveWalletRequest(request);
@@ -14604,6 +15056,9 @@ function createWalletCommand(deps) {
   const resolvedDeps = resolveWalletCommandDeps(deps);
   const wallet = new Command9("wallet").description("Manage wallet sessions");
   const request = new Command9("request").description("Inspect and finalize pending wallet requests");
+  const signer = new Command9("signer").description(
+    "Inspect and manage the stored local execution signer for a wallet"
+  );
   const smartAccount = new Command9("smart-account").description(
     "Predict and deploy zkSync smart-account contracts from a supplied artifact or built-in profile"
   );
@@ -14629,20 +15084,24 @@ function createWalletCommand(deps) {
     "after",
     [
       "",
-      "Default wallet path:",
+      "Local-first wallet path:",
       "  First bootstrap:",
       "    zk-agent wallet create --await-local",
       "    zk-agent next",
       "",
-      "  Restore a writable session for an existing wallet:",
+      "  Restore approval metadata for an existing wallet:",
       "    zk-agent wallet reapprove --name main --await-local",
       "    zk-agent next",
       "",
+      "  Attach a local signer when approval is still present:",
+      "    zk-agent wallet signer attach --name main --private-key <hex>",
+      "    zk-agent next",
+      "",
       "  Wallet-layer inspection:",
       "    zk-agent wallet status --name main",
       "    zk-agent wallet next --name main",
       "",
-      "  Remote approval path:",
+      "  Hosted remote approval path:",
       "    zk-agent relay inspect --relay-url <url>",
       "    zk-agent wallet create --relay-url <url> --wait-relay --prompt-code",
       "    zk-agent wallet reapprove --name main --relay-url <url> --wait-relay --prompt-code"
@@ -14662,6 +15121,21 @@ function createWalletCommand(deps) {
       "    zk-agent wallet request approve --request-id <id> --relay-url <url> --code <code> --wait"
     ].join("\n")
   );
+  signer.addHelpText(
+    "after",
+    [
+      "",
+      "Wallet signer path:",
+      "  Inspect the stored local execution signer state:",
+      "    zk-agent wallet signer show --name main",
+      "",
+      "  Attach a local execution signer without rebuilding approval metadata:",
+      "    zk-agent wallet signer attach --name main --private-key <hex>",
+      "",
+      "  Remove the stored local execution signer:",
+      "    zk-agent wallet signer remove --name main"
+    ].join("\n")
+  );
   smartAccount.addHelpText(
     "after",
     [
@@ -14785,7 +15259,9 @@ function createWalletCommand(deps) {
           ["approval url", request2.approvalUrl],
           ...relay ? [
             ["share url", relay.share_url],
-            ["status url", relay.status_url]
+            ["status url", relay.status_url],
+            ["share-link base", relay.share_url.replace(/\/[^/]+$/, "")],
+            ["status api base", relay.status_url.replace(/\/[^/]+$/, "")]
           ] : [],
           ["expires", request2.expiresAt],
           ["next local", buildWalletRequestAwaitLocalRecommendedCommand(request2.requestId)],
@@ -14932,7 +15408,9 @@ function createWalletCommand(deps) {
           ["approval url", request2.approvalUrl],
           ...relay ? [
             ["share url", relay.share_url],
-            ["status url", relay.status_url]
+            ["status url", relay.status_url],
+            ["share-link base", relay.share_url.replace(/\/[^/]+$/, "")],
+            ["status api base", relay.status_url.replace(/\/[^/]+$/, "")]
           ] : [],
           ["expires", request2.expiresAt],
           ["next local", buildWalletRequestAwaitLocalRecommendedCommand(request2.requestId)],
@@ -15030,7 +15508,56 @@ function createWalletCommand(deps) {
       }
     );
   });
-  wallet.command("export").description("Export one stored wallet as a portable backup bundle for later restore").option("--name <name>", "Wallet name", "main").option("--include-sensitive-data", "Include sessionPrivateKey in the exported bundle", false).action(async (options) => {
+  signer.command("show").description("Show the stored local execution signer state for a wallet").option("--name <name>", "Wallet name", "main").action(async (options) => {
+    const walletRecord = await requireWalletRecord(options.name);
+    printResult(walletSignerLines(walletRecord), {
+      ok: true,
+      wallet: sanitizeWalletRecord(walletRecord),
+      signer: walletSignerSummary(walletRecord),
+      nextAction: buildWalletFollowUpNextAction(walletRecord),
+      recommendedCommands: buildWalletFollowUpRecommendedCommands(walletRecord)
+    });
+  });
+  signer.command("attach").description("Attach a stored local execution signer to an existing wallet record").option("--name <name>", "Wallet name", "main").requiredOption("--private-key <hex>", "Local execution private key to store").action(async (options) => {
+    const walletRecord = await requireWalletRecord(options.name);
+    const privateKey = normalizePrivateKey(options.privateKey, "--private-key");
+    const nextWallet = migrateWalletSessionRecord({
+      ...walletRecord,
+      localExecutionAuthority: buildLocalExecutionAuthority({
+        privateKey,
+        signerType: "local",
+        source: "explicit-local-approval",
+        attachedAt: (/* @__PURE__ */ new Date()).toISOString()
+      }),
+      sessionPayload: clearLegacySessionPrivateKey(walletRecord.sessionPayload)
+    });
+    const note = walletRecord.sessionPayload ? void 0 : "No approved session metadata is stored yet. Attach succeeded, but wallet reapprove is still required before local write execution becomes usable.";
+    await saveWalletSession(nextWallet);
+    printResult(
+      walletSignerLines(nextWallet),
+      walletSignerAttachResult(nextWallet, note)
+    );
+  });
+  signer.command("remove").description("Remove the stored local execution signer from a wallet record").option("--name <name>", "Wallet name", "main").action(async (options) => {
+    const walletRecord = await requireWalletRecord(options.name);
+    const hadLocalExecutionKey = Boolean(resolveLocalExecutionPrivateKey(walletRecord));
+    const nextWallet = migrateWalletSessionRecord({
+      ...walletRecord,
+      localExecutionAuthority: void 0,
+      sessionPayload: clearLegacySessionPrivateKey(walletRecord.sessionPayload)
+    });
+    const note = hadLocalExecutionKey ? "Removed the stored local execution signer. Local write execution now requires signer attach or reapproval." : "No stored local execution signer was present.";
+    await saveWalletSession(nextWallet);
+    printResult(
+      walletSignerLines(nextWallet),
+      walletSignerAttachResult(nextWallet, note)
+    );
+  });
+  wallet.command("export").description("Export one stored wallet as a portable backup bundle for later restore").option("--name <name>", "Wallet name", "main").option(
+    "--include-sensitive-data",
+    "Include the stored local execution key and any legacy sessionPrivateKey mirror in the exported bundle",
+    false
+  ).action(async (options) => {
     const walletRecord = await requireWalletRecord(options.name);
     const bundle = exportWalletRecord(walletRecord, Boolean(options.includeSensitiveData));
     const recommendedCommands = {
@@ -15237,6 +15764,8 @@ function createWalletCommand(deps) {
         ["request", relay.request_id],
         ["share url", relay.share_url],
         ["status url", relay.status_url],
+        ["share-link base", relay.share_url.replace(/\/[^/]+$/, "")],
+        ["status api base", relay.status_url.replace(/\/[^/]+$/, "")],
         ["next status", buildWalletRequestRelayStatusRecommendedCommand(relay.request_id, options.relayUrl)],
         ["next approve", buildWalletRequestRelayApproveRecommendedCommand(relay.request_id, options.relayUrl)]
       ],
@@ -15265,6 +15794,8 @@ function createWalletCommand(deps) {
         ["request", relay.request_id],
         ["approval ready", relay.approval_ready ? "yes" : "no"],
         ["share url", relay.approval_url],
+        ["share-link base", relay.approval_url.replace(/\/[^/]+$/, "")],
+        ["status api base", `${relay.approval_url.replace(/\/r\/[^/]+$/, "")}/api/requests`],
         ["expires", relay.expires_at],
         ["next status", buildWalletRequestRelayStatusRecommendedCommand(relay.request_id, options.relayUrl)],
         ...relay.approval_ready ? [[
@@ -15335,7 +15866,7 @@ function createWalletCommand(deps) {
       }
     );
   });
-  request.command("approve-local").description("Manually construct an approved session payload from CLI inputs and save the resulting wallet").requiredOption("--request-id <id>", "Wallet request id").requiredOption("--wallet-address <address>", "Approved execution address (EOA address or smart-account address)").option("--owner-address <address>", "Owner / signer address for smart-account sessions").option("--name <name>", "Override saved wallet name").option("--session-address <address>", "Optional session address").option("--session-private-key <hex>", "Optional local private key for writable testnet sessions").option("--validator-address <address>", "Optional validator address").option("--paymaster-address <address>", "Optional paymaster address").option("--paymaster-token <address>", "Optional ERC-20 token used by an approval-based paymaster").option("--signer-type <type>", "Signer type", "connector").action(
+  request.command("approve-local").description("Manually construct an approved session payload from CLI inputs and save the resulting wallet").requiredOption("--request-id <id>", "Wallet request id").requiredOption("--wallet-address <address>", "Approved execution address (EOA address or smart-account address)").option("--owner-address <address>", "Owner / signer address for smart-account sessions").option("--name <name>", "Override saved wallet name").option("--session-address <address>", "Optional session address").option("--session-private-key <hex>", "Optional local execution private key for writable sessions").option("--validator-address <address>", "Optional validator address").option("--paymaster-address <address>", "Optional paymaster address").option("--paymaster-token <address>", "Optional ERC-20 token used by an approval-based paymaster").option("--signer-type <type>", "Optional signer type override: local, connector, or external").action(
     async (options) => {
       const walletRequest = await requireActiveWalletRequest(options.requestId);
       assertRequestActive(walletRequest.expiresAt);
@@ -15355,7 +15886,7 @@ function createWalletCommand(deps) {
         validatorAddress: options.validatorAddress,
         paymasterAddress: options.paymasterAddress,
         paymasterToken: options.paymasterToken,
-        signerType: options.signerType,
+        signerType: options.signerType ? normalizeSignerType(options.signerType) : void 0,
         connectorOrigin: connectorOriginFromUrl(walletRequest.connectorUrl),
         connectorUrl: walletRequest.connectorUrl
       });
@@ -16941,10 +17472,12 @@ function createWalletCommand(deps) {
   sedLite.addCommand(selectorAllowlistHook);
   smartAccount.addCommand(sedLite);
   smartAccount.addCommand(dailySpendLimit);
-  wallet.addCommand(smartAccount);
-  wallet.addCommand(paymaster);
   wallet.addCommand(request);
+  wallet.addCommand(signer);
+  wallet.addCommand(paymaster);
+  wallet.addCommand(smartAccount);
   applyCommandOrder(request, WALLET_REQUEST_HELP_COMMAND_ORDER);
+  applyCommandOrder(signer, WALLET_SIGNER_HELP_COMMAND_ORDER);
   applyCommandOrder(smartAccount, WALLET_SMART_ACCOUNT_HELP_COMMAND_ORDER);
   applyCommandOrder(wallet, WALLET_HELP_COMMAND_ORDER);
   return wallet;
@@ -17376,7 +17909,7 @@ function prependWorkflowRequestId(requestId, lines) {
   return [["workflow request", requestId], ...lines];
 }
 function workflowHasSessionApprovalBlocker(status) {
-  return status.blockingActionIds.some((actionId) => actionId === "reapprove" || actionId === "signer-mismatch");
+  return status.blockingActionIds.some((actionId) => actionId === "reapprove");
 }
 function workflowShouldEnsureWalletSession(options) {
   return Boolean(options.ensureWalletSession || options.awaitLocal);
@@ -17450,10 +17983,14 @@ async function ensureWorkflowWalletSession(input, deps) {
     goal: input.goal,
     options: input.options
   });
+  const paymasterInput = resolveWorkflowPaymasterInput(input.options);
   const reusableRequest = await deps.findReusableWalletRequest(input.wallet.walletName);
   const walletRequest = reusableRequest || await deps.createWalletReapprovalRequest({
     walletRecord: input.wallet,
     connectorUrl: input.options.connectorUrl,
+    ...paymasterInput?.mode ? {
+      paymasterMode: paymasterInput.mode
+    } : {},
     sessionPreset: policyRequestOptions.sessionPreset,
     sessionHours: policyRequestOptions.sessionHours,
     allowTransferTo: policyRequestOptions.allowTransferTo,
@@ -17538,6 +18075,7 @@ async function ensureWorkflowWalletSession(input, deps) {
 }
 function workflowWalletApprovalLines(walletApproval) {
   if (!walletApproval) return [];
+  const relayAliases = workflowWalletApprovalRelayAliases(walletApproval.relay);
   const lines = [
     ["wallet approval", walletApproval.stage],
     ["wallet request", walletApproval.request.requestId]
@@ -17557,6 +18095,12 @@ function workflowWalletApprovalLines(walletApproval) {
   if (walletApproval.relay?.status_url) {
     lines.push(["status url", walletApproval.relay.status_url]);
   }
+  if (relayAliases.walletApprovalRelayShareLinkBaseUrl) {
+    lines.push(["share-link base", relayAliases.walletApprovalRelayShareLinkBaseUrl]);
+  }
+  if (relayAliases.walletApprovalRelayStatusApiBaseUrl) {
+    lines.push(["status api base", relayAliases.walletApprovalRelayStatusApiBaseUrl]);
+  }
   if (walletApproval.stage === "request-created" && walletApproval.recommendedCommands) {
     lines.push(["next local", walletApproval.recommendedCommands.awaitLocal]);
     lines.push(["next remote", walletApproval.recommendedCommands.approve]);
@@ -17616,6 +18160,7 @@ async function printWorkflowRunCommandResult(execution) {
         result: execution.result,
         walletRequestId: execution.walletApproval?.request.requestId,
         walletApprovalRelay: execution.walletApproval?.relay,
+        ...workflowWalletApprovalRelayAliases(execution.walletApproval?.relay),
         walletApprovalRecommendedCommands: execution.walletApproval?.recommendedCommands,
         walletApproval: serializeWalletApproval(execution.walletApproval),
         recommendedCommands: recommendedCommands2
@@ -17657,6 +18202,7 @@ async function printWorkflowRunCommandResult(execution) {
       checkpoint: execution.checkpoint,
       walletRequestId: execution.walletApproval?.request.requestId,
       walletApprovalRelay: execution.walletApproval?.relay,
+      ...workflowWalletApprovalRelayAliases(execution.walletApproval?.relay),
       walletApprovalRecommendedCommands: execution.walletApproval?.recommendedCommands,
       walletApproval: serializeWalletApproval(execution.walletApproval),
       recommendedCommands
@@ -17806,6 +18352,17 @@ function buildWorkflowAutoCheckpoint(context, status) {
     status
   });
 }
+function applyWorkflowPayDefaults(options) {
+  return {
+    ...options,
+    intent: "send-native",
+    createCheckpoint: true,
+    executeWhenReady: true,
+    ensureWalletSession: true,
+    sessionPreset: options.sessionPreset?.trim() || "intent",
+    paymasterMode: options.paymasterMode?.trim() || "approval-based"
+  };
+}
 async function executeWorkflowAutoCommand(options, deps = resolveWorkflowCommandDeps(void 0)) {
   const { provider: provider4, defiProvider: defiProvider2 } = deps;
   const context = await resolveWorkflowAutoExecutionContext(options);
@@ -17946,6 +18503,7 @@ async function printWorkflowAutoCommandResult(execution) {
       checkpoint: execution.checkpoint,
       walletRequestId: execution.walletApproval?.request.requestId,
       walletApprovalRelay: execution.walletApproval?.relay,
+      ...workflowWalletApprovalRelayAliases(execution.walletApproval?.relay),
       walletApprovalRecommendedCommands: execution.walletApproval?.recommendedCommands,
       walletApproval: serializeWalletApproval(execution.walletApproval),
       recommendedCommands
@@ -18076,11 +18634,29 @@ function serializeWalletApproval(walletApproval) {
   if (!walletApproval) return void 0;
   return {
     ...walletApproval,
+    ...workflowWalletApprovalRelayAliases(walletApproval.relay, {
+      shareLinkBaseField: "relayShareLinkBaseUrl",
+      statusApiBaseField: "relayStatusApiBaseUrl"
+    }),
     walletRequestId: walletApproval.request.requestId,
     request: sanitizeWalletRequestRecord(walletApproval.request),
     wallet: walletApproval.wallet ? sanitizeWalletRecord(walletApproval.wallet) : void 0
   };
 }
+function workflowWalletApprovalRelayAliases(relay, fieldNames = {
+  shareLinkBaseField: "walletApprovalRelayShareLinkBaseUrl",
+  statusApiBaseField: "walletApprovalRelayStatusApiBaseUrl"
+}) {
+  const shareUrl = relay?.share_url;
+  const statusUrl = relay?.status_url;
+  const approvalUrl = relay?.approval_url;
+  const shareLinkBaseUrl = shareUrl ? shareUrl.replace(/\/[^/]+$/, "") : approvalUrl ? approvalUrl.replace(/\/[^/]+$/, "") : void 0;
+  const statusApiBaseUrl = statusUrl ? statusUrl.replace(/\/[^/]+$/, "") : approvalUrl && relay?.request_id ? `${approvalUrl.replace(/\/r\/[^/]+$/, "")}/api/requests` : void 0;
+  return {
+    [fieldNames.shareLinkBaseField]: shareLinkBaseUrl,
+    [fieldNames.statusApiBaseField]: statusApiBaseUrl
+  };
+}
 function addWorkflowGoalOptions(command, config = {}) {
   if (config.includeExecutionFlags) {
     command.option("--broadcast", "Broadcast the underlying transaction(s) instead of returning a preview", false).option(
@@ -18360,6 +18936,9 @@ function buildWorkflowHelpText() {
     "  Guided default:",
     "    zk-agent workflow auto --wallet main --intent <intent> [goal flags] --create-checkpoint --execute-when-ready",
     "",
+    "  Flagship native pay path:",
+    "    zk-agent workflow pay --wallet main --to <address> --amount <amount>",
+    "",
     "  Checkpointed execution:",
     "    zk-agent workflow start --wallet main --intent <intent> [goal flags]",
     "    zk-agent workflow status --request-id <id>",
@@ -18375,6 +18954,7 @@ function buildWorkflowHelpText() {
 }
 var WORKFLOW_HELP_COMMAND_ORDER = [
   "auto",
+  "pay",
   "start",
   "status",
   "next",
@@ -18598,6 +19178,23 @@ function createWorkflowCommand(deps) {
     const execution = await executeWorkflowAutoCommand(options, resolvedDeps);
     await printWorkflowAutoCommandResult(execution);
   }));
+  const pay = workflow.command("pay").description(
+    "Guided flagship AA native-send path with checkpoint persistence, intent-scoped session recovery, and paymaster-aware defaults"
+  ).option("--wallet <name>", "Wallet name", "main").option(
+    "--request-id <id>",
+    "Load the workflow definition from a stored checkpoint, or reserve this id for the flagship pay path"
+  );
+  addWorkflowGoalOptions(pay, {
+    includeExecutionFlags: true,
+    includeFundingDispatch: true,
+    includeLocalApproval: true
+  }).action(withWorkflowInputErrorHandling(async (options) => {
+    const execution = await executeWorkflowAutoCommand(
+      applyWorkflowPayDefaults(options),
+      resolvedDeps
+    );
+    await printWorkflowAutoCommandResult(execution);
+  }));
   const run = workflow.command("run").description("Run the requested workflow, or stop on the next required prerequisite or funding step first").option(
     "--intent <intent>",
     "send-native, send-token, call-write, swap, bridge, deposit, or withdraw"
@@ -18653,6 +19250,7 @@ function createWorkflowCommand(deps) {
         checkpoint: inspection.checkpoint,
         walletRequestId: inspection.walletApproval?.request.requestId,
         walletApprovalRelay: inspection.walletApproval?.relay,
+        ...workflowWalletApprovalRelayAliases(inspection.walletApproval?.relay),
         walletApprovalRecommendedCommands: inspection.walletApproval?.recommendedCommands,
         walletApproval: serializeWalletApproval(inspection.walletApproval),
         recommendedCommands
@@ -18716,6 +19314,7 @@ function createWorkflowCommand(deps) {
         checkpoint: inspection.checkpoint,
         walletRequestId: inspection.walletApproval?.request.requestId,
         walletApprovalRelay: inspection.walletApproval?.relay,
+        ...workflowWalletApprovalRelayAliases(inspection.walletApproval?.relay),
         walletApprovalRecommendedCommands: inspection.walletApproval?.recommendedCommands,
         walletApproval: serializeWalletApproval(inspection.walletApproval),
         recommendedCommands
@@ -18767,6 +19366,7 @@ function createWorkflowCommand(deps) {
           checkpoint: inspection.checkpoint,
           walletRequestId: inspection.walletApproval.request.requestId,
           walletApprovalRelay: inspection.walletApproval.relay,
+          ...workflowWalletApprovalRelayAliases(inspection.walletApproval.relay),
           walletApprovalRecommendedCommands: inspection.walletApproval.recommendedCommands,
           walletApproval: serializeWalletApproval(inspection.walletApproval),
           recommendedCommands: recommendedCommands2
@@ -18817,6 +19417,7 @@ function createWorkflowCommand(deps) {
           checkpoint: execution.checkpoint,
           walletRequestId: execution.walletApproval?.request.requestId,
           walletApprovalRelay: execution.walletApproval?.relay,
+          ...workflowWalletApprovalRelayAliases(execution.walletApproval?.relay),
           walletApprovalRecommendedCommands: execution.walletApproval?.recommendedCommands,
           walletApproval: serializeWalletApproval(execution.walletApproval),
           recommendedCommands: recommendedCommands2
@@ -18858,6 +19459,7 @@ function createWorkflowCommand(deps) {
         result: execution.result,
         walletRequestId: inspection.walletApproval?.request.requestId,
         walletApprovalRelay: inspection.walletApproval?.relay,
+        ...workflowWalletApprovalRelayAliases(inspection.walletApproval?.relay),
         walletApprovalRecommendedCommands: inspection.walletApproval?.recommendedCommands,
         walletApproval: serializeWalletApproval(inspection.walletApproval),
         recommendedCommands
@@ -18895,14 +19497,15 @@ function createWorkflowCommand(deps) {
 function buildDefaultOperatorPathHelpText() {
   return [
     "",
-    "Default operator path:",
+    "Default local-first operator path:",
     "  zk-agent setup",
     "  zk-agent next",
     "  zk-agent wallet create --await-local",
     "  zk-agent next",
-    `  ${buildWorkflowAutoRecommendedCommand("main")}`,
+    `  ${buildWorkflowPayRecommendedCommand("main")}`,
     "",
     "Use `zk-agent next --request-id <id>` to continue a stored workflow checkpoint.",
+    "Use `zk-agent relay inspect --relay-url <url>` and `zk-agent wallet --help` for the hosted remote-approval path.",
     "Use `zk-agent wallet --help` for bootstrap/reapproval details and `zk-agent workflow --help` once the intent is known."
   ].join("\n");
 }