mnemospark 0.7.0 → 0.8.1

package/dist/index.js

@@ -791,9 +791,14 @@ async function forwardPaymentSettleToBackend(quoteId, walletAddress, options = {
   }
   const targetUrl = `${normalizeBaseUrl(backendBaseUrl)}/payment/settle`;
   const requestBody = {
-    quote_id: quoteId,
     wallet_address: walletAddress
   };
+  if (options.renewal === true && options.objectKey?.trim()) {
+    requestBody.renewal = true;
+    requestBody.object_key = options.objectKey.trim();
+  } else {
+    requestBody.quote_id = quoteId;
+  }
   if (options.payment) {
     requestBody.payment = options.payment;
   }
@@ -820,9 +825,14 @@ async function requestPaymentSettleViaProxy(quoteId, walletAddress, options = {}
   );
   const targetUrl = `${baseUrl}${PAYMENT_SETTLE_PROXY_PATH}`;
   const requestBody = {
-    quote_id: quoteId,
     wallet_address: walletAddress
   };
+  if (options.renewal === true && options.objectKey?.trim()) {
+    requestBody.renewal = true;
+    requestBody.object_key = options.objectKey.trim();
+  } else {
+    requestBody.quote_id = quoteId;
+  }
   if (options.payment) {
     requestBody.payment = options.payment;
   }
@@ -1244,6 +1254,23 @@ function parseJsonText(text, errorMessage) {
   }
   return record;
 }
+var MAX_LOCAL_FRIENDLY_BASENAME_LEN = 200;
+function sanitizeFriendlyNameForLocalBasename(raw) {
+  const normalized = raw.replace(/\\/g, "/").trim();
+  if (!normalized) {
+    throw new Error("Friendly name is empty");
+  }
+  const segments = normalized.split("/").filter((segment2) => segment2.length > 0 && segment2 !== "." && segment2 !== "..");
+  const segment = segments[segments.length - 1] ?? "";
+  if (!segment || segment === "." || segment === "..") {
+    throw new Error("Invalid friendly name for local file path");
+  }
+  const noCtrl = segment.replace(/[\x00-\x1f]/g, "").trim();
+  if (!noCtrl || noCtrl === "." || noCtrl === "..") {
+    throw new Error("Invalid friendly name for local file path");
+  }
+  return noCtrl.length > MAX_LOCAL_FRIENDLY_BASENAME_LEN ? noCtrl.slice(0, MAX_LOCAL_FRIENDLY_BASENAME_LEN) : noCtrl;
+}
 function sanitizeObjectKeyToRelativePath(objectKey) {
   const normalized = objectKey.replace(/\\/g, "/").trim().replace(/^\/+/, "");
   const segments = normalized.split("/").filter((segment) => segment.length > 0 && segment !== "." && segment !== "..");
@@ -1387,6 +1414,27 @@ function parseStorageObjectRequest(payload) {
     location
   };
 }
+function parseProxyStorageDownloadPayload(payload) {
+  const record = asRecord(payload);
+  if (!record) {
+    return null;
+  }
+  const walletAddress = asNonEmptyString(record.wallet_address);
+  const objectKey = asNonEmptyString(record.object_key);
+  const location = asNonEmptyString(record.location) ?? void 0;
+  if (!walletAddress || !objectKey) {
+    return null;
+  }
+  const localRaw = asNonEmptyString(record.mnemospark_local_filename) ?? void 0;
+  return {
+    request: {
+      wallet_address: walletAddress,
+      object_key: objectKey,
+      ...location ? { location } : {}
+    },
+    ...localRaw ? { localBasename: localRaw } : {}
+  };
+}
 function jsonBodyForObjectRequest(request) {
   const o = {
     wallet_address: request.wallet_address,
@@ -1397,6 +1445,14 @@ function jsonBodyForObjectRequest(request) {
   }
   return o;
 }
+function jsonBodyForProxyDownloadRequest(request, downloadLocalBasename) {
+  const body = jsonBodyForObjectRequest(request);
+  const trimmed = downloadLocalBasename?.trim();
+  if (trimmed) {
+    body.mnemospark_local_filename = trimmed;
+  }
+  return body;
+}
 function jsonBodyForLsRequest(request) {
   const o = { wallet_address: request.wallet_address };
   if (request.object_key) {
@@ -1542,7 +1598,7 @@ async function requestStorageLsViaProxy(request, options = {}) {
 async function requestStorageDownloadViaProxy(request, options = {}) {
   return requestJsonViaProxy(
     STORAGE_DOWNLOAD_PROXY_PATH,
-    jsonBodyForObjectRequest(request),
+    jsonBodyForProxyDownloadRequest(request, options.downloadLocalBasename),
     parseStorageDownloadProxyResponse,
     options
   );
@@ -1629,7 +1685,8 @@ async function downloadStorageToDisk(request, backendResponse, options = {}) {
       objectKey = filenameFromHeader;
     }
   }
-  const filePath = resolveDownloadPath(outputDir, objectKey);
+  const pathKey = options.localOutputBasename?.trim() && options.localOutputBasename.trim().length > 0 ? options.localOutputBasename.trim() : objectKey;
+  const filePath = resolveDownloadPath(outputDir, pathKey);
   await mkdir(dirname(filePath), { recursive: true });
   await writeFile(filePath, bytes);
   return {
@@ -1994,16 +2051,47 @@ async function startProxy(options) {
           return;
         }
         const record = payload && typeof payload === "object" ? payload : null;
-        const quoteId = typeof record?.quote_id === "string" ? record.quote_id.trim() : "";
         const walletAddress = typeof record?.wallet_address === "string" ? record.wallet_address.trim() : "";
+        const isRenewal = record?.renewal === true;
+        const objectKey = typeof record?.object_key === "string" ? record.object_key.trim() : "";
+        let quoteId = typeof record?.quote_id === "string" ? record.quote_id.trim() : "";
         const inlinePayment = record?.payment;
         const inlinePaymentAuthorization = record?.payment_authorization;
-        if (!quoteId || !walletAddress) {
+        if (!walletAddress) {
           logProxyEvent("warn", "proxy_payment_settle_missing_fields");
           emitProxyTerminalFromStatus(correlation, 400, { reason: "missing_fields" });
           sendJson(res, 400, {
             error: "Bad request",
-            message: "Missing required fields: quote_id, wallet_address"
+            message: "Missing required field: wallet_address"
+          });
+          return;
+        }
+        if (isRenewal) {
+          if (quoteId) {
+            logProxyEvent("warn", "proxy_payment_settle_renewal_with_quote_id");
+            emitProxyTerminalFromStatus(correlation, 400, { reason: "renewal_with_quote_id" });
+            sendJson(res, 400, {
+              error: "Bad request",
+              message: "renewal requests must not include quote_id"
+            });
+            return;
+          }
+          if (!objectKey) {
+            logProxyEvent("warn", "proxy_payment_settle_missing_fields");
+            emitProxyTerminalFromStatus(correlation, 400, { reason: "missing_fields" });
+            sendJson(res, 400, {
+              error: "Bad request",
+              message: "Missing required field: object_key (renewal mode)"
+            });
+            return;
+          }
+          quoteId = `renewal:${objectKey}`;
+        } else if (!quoteId) {
+          logProxyEvent("warn", "proxy_payment_settle_missing_fields");
+          emitProxyTerminalFromStatus(correlation, 400, { reason: "missing_fields" });
+          sendJson(res, 400, {
+            error: "Bad request",
+            message: "Missing required field: quote_id (or use renewal: true with object_key)"
           });
           return;
         }
@@ -2062,7 +2150,9 @@ async function startProxy(options) {
           paymentSignature: readHeaderValue(req.headers["payment-signature"]),
           legacyPayment: readHeaderValue(req.headers["x-payment"]),
           payment: inlinePayment && typeof inlinePayment === "object" && !Array.isArray(inlinePayment) ? inlinePayment : void 0,
-          paymentAuthorization: typeof inlinePaymentAuthorization === "string" ? inlinePaymentAuthorization.trim() || void 0 : inlinePaymentAuthorization !== void 0 ? inlinePaymentAuthorization : void 0
+          paymentAuthorization: typeof inlinePaymentAuthorization === "string" ? inlinePaymentAuthorization.trim() || void 0 : inlinePaymentAuthorization !== void 0 ? inlinePaymentAuthorization : void 0,
+          renewal: isRenewal,
+          objectKey: isRenewal ? objectKey : void 0
         });
         logProxyEvent("info", "proxy_payment_settle_backend_response", {
           status: backendResponse.status
@@ -2502,8 +2592,8 @@ async function startProxy(options) {
           });
           return;
         }
-        const requestPayload = parseStorageObjectRequest(payload);
-        if (!requestPayload) {
+        const parsedDownload = parseProxyStorageDownloadPayload(payload);
+        if (!parsedDownload) {
           logProxyEvent("warn", "proxy_download_missing_fields");
           emitProxyTerminalFromStatus(correlation, 400, { reason: "missing_fields" });
           sendJson(res, 400, {
@@ -2512,6 +2602,8 @@ async function startProxy(options) {
           });
           return;
         }
+        const requestPayload = parsedDownload.request;
+        const downloadLocalBasename = parsedDownload.localBasename;
         correlation.wallet_address = requestPayload.wallet_address;
         correlation.object_key = requestPayload.object_key;
         if (requestPayload.wallet_address.toLowerCase() !== proxyWalletAddressLower) {
@@ -2573,7 +2665,8 @@ async function startProxy(options) {
           return;
         }
         const downloadResult = await downloadStorageToDisk(requestPayload, backendResponse, {
-          outputDir: resolveDownloadOutputDir()
+          outputDir: resolveDownloadOutputDir(),
+          ...downloadLocalBasename?.trim() ? { localOutputBasename: downloadLocalBasename.trim() } : {}
         });
         logProxyEvent("info", "proxy_download_written_to_disk", {
           key: downloadResult.key,
@@ -2932,7 +3025,7 @@ import {
   randomUUID as randomUUID3
 } from "crypto";
 import { createReadStream as createReadStream2, statfsSync } from "fs";
-import { appendFile as appendFile2, lstat, mkdir as mkdir5, readFile as readFile3, readdir as readdir2, rm, stat as stat2, writeFile as writeFile3 } from "fs/promises";
+import { lstat, mkdir as mkdir5, readFile as readFile3, readdir as readdir2, rm, stat as stat2, writeFile as writeFile3 } from "fs/promises";
 import { homedir as homedir6 } from "os";
 import { basename as basename2, dirname as dirname5, join as join8, resolve as resolve2 } from "path";
 import { privateKeyToAccount as privateKeyToAccount5 } from "viem/accounts";
@@ -3039,8 +3132,8 @@ function formatNextCronUtc(schedule, cronStatus, now) {
 }
 function buildLsProseIntro(bucket) {
   return [
-    "\u2601\uFE0F mnemospark cloud files",
-    `S3 bucket: ${bucket}`,
+    "\u2601\uFE0F mnemospark cloud",
+    `Folder: ${bucket}`,
     "The columns: CRON JOB, NEXT PAYMENT DATE, AMOUNT DUE, FILE NAME are from this host's mnemospark SQLite catalog",
     "mnemospark cloud only stores the OBJECT-KEY for privacy"
   ];
@@ -3470,6 +3563,22 @@ async function createCloudDatastore(homeDir) {
       if (!row) return null;
       return { cronId: row.cron_id, objectId: row.object_id };
     }, null),
+    findCronJobRowByObjectKey: async (objectKey) => safe(() => {
+      const row = db.prepare(
+        `SELECT cron_id, object_id, object_key, quote_id, schedule, command, status
+             FROM cron_jobs WHERE object_key = ? ORDER BY updated_at DESC LIMIT 1`
+      ).get(objectKey);
+      if (!row) return null;
+      return {
+        cron_id: row.cron_id,
+        object_id: row.object_id,
+        object_key: row.object_key,
+        quote_id: row.quote_id,
+        schedule: row.schedule,
+        command: row.command,
+        status: row.status
+      };
+    }, null),
     findCronByQuoteId: async (quoteId) => safe(() => {
       const row = db.prepare(
         `SELECT cron_id, object_id, object_key, quote_id, schedule, command, status
@@ -3656,6 +3765,16 @@ async function createCloudDatastore(homeDir) {
       ).get(w, obj.object_id);
       return byObj?.friendly_name ?? null;
     }, null),
+    findLatestFriendlyNameForObjectId: async (objectId) => safe(() => {
+      const row = db.prepare(
+        `SELECT friendly_name
+             FROM friendly_names
+             WHERE object_id = ? AND is_active = 1
+             ORDER BY created_at DESC
+             LIMIT 1`
+      ).get(objectId.trim());
+      return row?.friendly_name ?? null;
+    }, null),
     findCronAndPaymentForObjectKey: async (walletAddress, objectKey) => safe(() => {
       const w = normalizeWalletAddress(walletAddress);
       const cron = db.prepare(
@@ -3692,20 +3811,19 @@ async function createCloudDatastore(homeDir) {
 var SUPPORTED_BACKUP_PLATFORMS = /* @__PURE__ */ new Set(["darwin", "linux"]);
 var BACKUP_DIR_SUBPATH = join8(".openclaw", "mnemospark", "backup");
 var DEFAULT_BACKUP_DIR = join8(homedir6(), BACKUP_DIR_SUBPATH);
-var CRON_TABLE_SUBPATH = join8(".openclaw", "mnemospark", "crontab.txt");
 var BLOCKRUN_WALLET_KEY_SUBPATH = join8(".openclaw", "blockrun", "wallet.key");
 var MNEMOSPARK_WALLET_KEY_SUBPATH = join8(".openclaw", "mnemospark", "wallet", "wallet.key");
 var INLINE_UPLOAD_MAX_BYTES = 45e5;
-var PAYMENT_REMINDER_INTERVAL_DAYS = 30;
-var PAYMENT_DELETE_DEADLINE_DAYS = 32;
 var PAYMENT_CRON_SCHEDULE = "0 0 1 * *";
 var TAR_OVERHEAD_BYTES = 10 * 1024 * 1024;
 var QUOTE_VALIDITY_USER_NOTE = "Quotes are valid for one hour. Please run price-storage again if you need a new quote.";
 var MNEMOSPARK_SUPPORT_EMAIL = "pluggedin@mnemospark.ai";
-var CLOUD_HELP_FOOTER_STATE = "Local state: mnemospark records quotes, objects, payments, cron jobs, friendly names, and operation metadata in ~/.openclaw/mnemospark/state.db (SQLite). For troubleshooting and correlation, commands and the HTTP proxy append structured JSON lines to ~/.openclaw/mnemospark/events.jsonl. Monthly storage billing jobs are listed in ~/.openclaw/mnemospark/crontab.txt for your system scheduler.";
+var CLOUD_HELP_FOOTER_STATE = "Local state: mnemospark records quotes, objects, payments, cron jobs, friendly names, and operation metadata in ~/.openclaw/mnemospark/state.db (SQLite). For troubleshooting and correlation, commands and the HTTP proxy append structured JSON lines to ~/.openclaw/mnemospark/events.jsonl. Monthly storage billing jobs are listed in ~/.openclaw/cron/jobs.json for OpenClaw scheduling.";
 var REQUIRED_PRICE_STORAGE = "--wallet-address, --object-id, --object-id-hash, --gb, --provider, --region";
 var REQUIRED_UPLOAD = "--quote-id, --wallet-address, --object-id, --object-id-hash";
-var REQUIRED_PAYMENT_SETTLE = "--quote-id and --wallet-address";
+var REQUIRED_BACKUP = "<file|directory> and --name <friendly-name>";
+var REQUIRED_PAYMENT_SETTLE = "--wallet-address and (--quote-id | --renewal with --object-key)";
+var PAYMENT_SETTLE_BOOLEAN_FLAGS = /* @__PURE__ */ new Set(["renewal"]);
 var REQUIRED_STORAGE_OBJECT = "--wallet-address and one of (--object-key | --name [--latest|--at])";
 var REQUIRED_LS = "--wallet-address (for one object add --object-key or --name [--latest|--at]; omit both to list the bucket)";
 var PAYMENT_SETTLE_FLAG_NAMES = /* @__PURE__ */ new Set([
@@ -3713,7 +3831,8 @@ var PAYMENT_SETTLE_FLAG_NAMES = /* @__PURE__ */ new Set([
   "wallet-address",
   "object-id",
   "object-key",
-  "storage-price"
+  "storage-price",
+  "renewal"
 ]);
 var BOOLEAN_SELECTOR_FLAGS = /* @__PURE__ */ new Set(["latest"]);
 var BOOLEAN_ASYNC_FLAGS = /* @__PURE__ */ new Set(["async"]);
@@ -3737,9 +3856,9 @@ var CLOUD_HELP_TEXT = [
   "",
   "\u2022 `/mnemospark_cloud` or `/mnemospark_cloud help` \u2014 show this message",
   "",
-  "\u2022 `/mnemospark_cloud backup <file|directory> [--name <friendly-name>] [--async] [--orchestrator <inline|subagent>] [--timeout-seconds <n>]`",
-  "  Purpose: create a local tar+gzip archive under ~/.openclaw/mnemospark/backup and record metadata in SQLite for later price-storage and upload.",
-  "  Required: <file|directory>",
+  "\u2022 `/mnemospark_cloud backup <file|directory> --name <friendly-name> [--async] [--orchestrator <inline|subagent>] [--timeout-seconds <n>]`",
+  "  Purpose: create a local tar+gzip archive under ~/.openclaw/mnemospark/backup (filename from sanitized friendly name) and record metadata in SQLite for later price-storage and upload.",
+  "  Required: " + REQUIRED_BACKUP,
   "",
   "\u2022 `/mnemospark_cloud price-storage --wallet-address <addr> --object-id <id> --object-id-hash <hash> --gb <gb> --provider <provider> --region <region>`",
   "  Purpose: request a storage quote before upload.",
@@ -3749,9 +3868,9 @@ var CLOUD_HELP_TEXT = [
   "  Purpose: upload an encrypted object using a valid quote-id.",
   "  Required: " + REQUIRED_UPLOAD,
   "",
-  "\u2022 `/mnemospark_cloud payment-settle --quote-id <quote-id> --wallet-address <addr> [--object-id <id>] [--object-key <key>] [--storage-price <n>]`",
-  "  Purpose: settle storage payment for a quote (e.g. monthly cron). Uses the same proxy + x402 path as upload pre-settlement.",
-  "  Required: --quote-id, --wallet-address (wallet private key must match the address).",
+  "\u2022 `/mnemospark_cloud payment-settle (--quote-id <quote-id> | --renewal --object-key <key>) --wallet-address <addr> [--object-id <id>] [--storage-price <n>]`",
+  "  Purpose: settle storage payment before upload (quote) or on the monthly cron (renewal, no new quote). Uses the same proxy + x402 path as upload pre-settlement.",
+  "  Required: " + REQUIRED_PAYMENT_SETTLE + " (wallet private key must match the address).",
   "",
   "\u2022 `/mnemospark_cloud ls --wallet-address <addr> [--object-key <key> | --name <friendly-name> | omit both to list bucket] [--latest|--at <timestamp>]`",
   "  Purpose: stat one object or list all keys in the wallet bucket (S3).",
@@ -3789,7 +3908,7 @@ var CLOUD_HELP_TEXT = [
   "",
   CLOUD_HELP_FOOTER_STATE,
   "",
-  "Commands price-storage, upload, ls, download, delete, and payment-settle require --wallet-address."
+  "Backup uses your configured mnemospark wallet key (no `--wallet-address` flag). Commands price-storage, upload, ls, download, delete, and payment-settle require `--wallet-address` on the command line (must match that wallet)."
 ].join("\n");
 var UnsupportedBackupPlatformError = class extends Error {
   constructor(platform) {
@@ -3988,10 +4107,14 @@ function parseCloudArgs(args) {
     if (!asyncArgs) {
       return { mode: "backup-invalid-async" };
     }
+    const friendlyName = flags.name?.trim();
+    if (!friendlyName) {
+      return { mode: "backup-invalid-name" };
+    }
     return {
       mode: "backup",
       backupTarget,
-      friendlyName: flags.name?.trim() || void 0,
+      friendlyName,
       ...asyncArgs
     };
   }
@@ -4043,7 +4166,7 @@ function parseCloudArgs(args) {
     };
   }
   if (subcommand === "payment-settle") {
-    const flags = parseNamedFlags(rest);
+    const flags = parseNamedFlags(rest, PAYMENT_SETTLE_BOOLEAN_FLAGS);
     if (!flags) {
       return { mode: "payment-settle-invalid" };
     }
@@ -4052,9 +4175,21 @@ function parseCloudArgs(args) {
         return { mode: "payment-settle-invalid" };
       }
     }
-    const quoteId = flags["quote-id"]?.trim();
     const walletAddress = flags["wallet-address"]?.trim();
-    if (!quoteId || !walletAddress) {
+    if (!walletAddress) {
+      return { mode: "payment-settle-invalid" };
+    }
+    const isRenewal = flags.renewal === "true";
+    const quoteId = flags["quote-id"]?.trim();
+    const objectKey = flags["object-key"]?.trim();
+    if (isRenewal) {
+      if (quoteId) {
+        return { mode: "payment-settle-invalid" };
+      }
+      if (!objectKey) {
+        return { mode: "payment-settle-invalid" };
+      }
+    } else if (!quoteId) {
       return { mode: "payment-settle-invalid" };
     }
     let storagePrice;
@@ -4069,10 +4204,11 @@ function parseCloudArgs(args) {
     return {
       mode: "payment-settle",
       paymentSettleRequest: {
-        quote_id: quoteId,
         wallet_address: walletAddress,
+        renewal: isRenewal || void 0,
+        quote_id: quoteId || void 0,
         object_id: flags["object-id"]?.trim() || void 0,
-        object_key: flags["object-key"]?.trim() || void 0,
+        object_key: objectKey || void 0,
         storage_price: storagePrice
       }
     };
@@ -4162,9 +4298,6 @@ function parseCloudArgs(args) {
   }
   return { mode: "unknown" };
 }
-function resolveCronTablePath(homeDir) {
-  return join8(homeDir ?? homedir6(), CRON_TABLE_SUBPATH);
-}
 async function calculateInputSizeBytes(targetPath) {
   const targetStats = await lstat(targetPath);
   if (targetStats.isFile() || targetStats.isSymbolicLink()) {
@@ -4218,6 +4351,38 @@ async function sha256File(filePath) {
   });
   return hash.digest("hex");
 }
+async function resolveLocalUploadArchivePath(backupDir, objectId, friendlyName) {
+  if (friendlyName?.trim()) {
+    try {
+      const sanitized = sanitizeFriendlyNameForLocalBasename(friendlyName);
+      const candidate = join8(backupDir, sanitized);
+      try {
+        const st = await stat2(candidate);
+        if (st.isFile()) {
+          return { ok: true, archivePath: candidate };
+        }
+      } catch {
+      }
+    } catch {
+    }
+  }
+  const legacyPath = join8(backupDir, objectId);
+  try {
+    const legacyStats = await stat2(legacyPath);
+    if (!legacyStats.isFile()) {
+      return {
+        ok: false,
+        message: `Cannot upload storage object: local archive path is not a file (${legacyPath}).`
+      };
+    }
+    return { ok: true, archivePath: legacyPath };
+  } catch {
+    return {
+      ok: false,
+      message: `Cannot upload storage object: local archive not found. Run /mnemospark_cloud backup with --name (canonical layout) or restore the legacy file at ${legacyPath}.`
+    };
+  }
+}
 function createObjectId(options) {
   const nowFn = options.now ?? Date.now;
   const randomFn = options.randomBytes ?? randomBytesNode;
@@ -4255,7 +4420,25 @@ async function buildBackupObject(targetPathArg, options = {}) {
     throw new Error("Insufficient disk space for backup object");
   }
   const objectId = createObjectId(options);
-  const archivePath = join8(tmpDir, objectId);
+  const archiveBaseSegment = options.archiveBasename?.trim() || objectId;
+  const archivePath = join8(tmpDir, archiveBaseSegment);
+  if (options.archiveBasename?.trim()) {
+    try {
+      const existing = await stat2(archivePath);
+      if (existing.isFile() || existing.isDirectory()) {
+        throw new Error(
+          `Backup archive path already exists: ${archivePath}. Choose a different --name.`
+        );
+      }
+    } catch (err) {
+      if (err instanceof Error && err.message.includes("already exists")) {
+        throw err;
+      }
+      if (err.code !== "ENOENT") {
+        throw err;
+      }
+    }
+  }
   try {
     await runTarGzip(archivePath, targetPath);
     const archiveStats = await stat2(archivePath);
@@ -4272,84 +4455,126 @@ async function buildBackupObject(targetPathArg, options = {}) {
     throw error;
   }
 }
-function formatTimestamp(date) {
-  const pad = (value) => value.toString().padStart(2, "0");
-  return [
-    date.getFullYear().toString(),
-    "-",
-    pad(date.getMonth() + 1),
-    "-",
-    pad(date.getDate()),
-    " ",
-    pad(date.getHours()),
-    ":",
-    pad(date.getMinutes()),
-    ":",
-    pad(date.getSeconds())
-  ].join("");
-}
-function parseStoragePaymentCronJobLine(line) {
-  const trimmed = line.trim();
-  if (!trimmed) {
+function normalizeOpenClawCronJobForLookup(value) {
+  if (!value || typeof value !== "object") {
     return null;
   }
-  let payload;
-  try {
-    payload = JSON.parse(trimmed);
-  } catch {
+  const record = value;
+  const jobIdRaw = typeof record.jobId === "string" ? record.jobId : record.id;
+  const jobId = typeof jobIdRaw === "string" ? jobIdRaw.trim() : "";
+  const payloadRaw = record.payload;
+  if (!jobId || !payloadRaw || typeof payloadRaw !== "object") {
     return null;
   }
-  if (!payload || typeof payload !== "object") {
-    return null;
-  }
-  const record = payload;
-  const cronId = typeof record.cronId === "string" ? record.cronId.trim() : "";
-  const createdAt = typeof record.createdAt === "string" ? record.createdAt.trim() : "";
-  const schedule = typeof record.schedule === "string" ? record.schedule.trim() : "";
-  const command = typeof record.command === "string" ? record.command.trim() : "";
-  const quoteId = typeof record.quoteId === "string" ? record.quoteId.trim() : "";
-  const storagePrice = typeof record.storagePrice === "number" ? record.storagePrice : Number.NaN;
-  const walletAddress = typeof record.walletAddress === "string" ? record.walletAddress.trim() : "";
-  const objectId = typeof record.objectId === "string" ? record.objectId.trim() : "";
-  const objectKey = typeof record.objectKey === "string" ? record.objectKey.trim() : "";
-  const provider = typeof record.provider === "string" ? record.provider.trim() : "";
-  const bucketName = typeof record.bucketName === "string" ? record.bucketName.trim() : "";
-  const location = typeof record.location === "string" ? record.location.trim() : "";
-  if (!cronId || !createdAt || !schedule || !command || !quoteId || !Number.isFinite(storagePrice) || storagePrice <= 0 || !walletAddress || !objectId || !objectKey || !provider || !bucketName || !location) {
+  const payloadRecord = payloadRaw;
+  const payloadKind = payloadRecord.kind;
+  const payloadMessage = typeof payloadRecord.message === "string" ? payloadRecord.message.trim() : "";
+  if (payloadKind !== "agentTurn" || !payloadMessage) {
     return null;
   }
   return {
-    cronId,
-    createdAt,
-    schedule,
-    command,
-    quoteId,
-    storagePrice,
-    walletAddress,
-    objectId,
-    objectKey,
-    provider,
-    bucketName,
-    location
+    jobId,
+    message: payloadMessage
   };
 }
-async function findCronJobInCrontabByObjectKey(objectKey, homeDir) {
-  const cronTablePath = resolveCronTablePath(homeDir);
-  let content;
+async function runOpenClawCli(args, homeDir) {
+  return await new Promise((resolvePromise, rejectPromise) => {
+    let stdout = "";
+    let stderr = "";
+    const child = spawn("openclaw", args, {
+      stdio: ["ignore", "pipe", "pipe"],
+      env: {
+        ...process.env,
+        HOME: homeDir ?? process.env.HOME
+      }
+    });
+    child.stdout.on("data", (chunk) => {
+      stdout += chunk.toString();
+    });
+    child.stderr.on("data", (chunk) => {
+      stderr += chunk.toString();
+    });
+    child.on("error", rejectPromise);
+    child.on("close", (code) => {
+      if (code === 0) {
+        resolvePromise({ stdout, stderr });
+        return;
+      }
+      rejectPromise(
+        new Error(
+          stderr.trim() || stdout.trim() || `openclaw ${args.join(" ")} exited with code ${code ?? "unknown"}`
+        )
+      );
+    });
+  });
+}
+function parseOpenClawCliJson(stdout, commandLabel) {
+  const trimmed = stdout.trim();
+  if (!trimmed) {
+    throw new Error(`openclaw ${commandLabel} returned empty JSON output`);
+  }
   try {
-    content = await readFile3(cronTablePath, "utf-8");
-  } catch (error) {
-    if (error.code === "ENOENT") {
-      return null;
-    }
-    throw error;
+    return JSON.parse(trimmed);
+  } catch {
+    throw new Error(`openclaw ${commandLabel} returned invalid JSON output`);
   }
-  const lines = content.split(/\r?\n/).map((line) => line.trim()).filter((line) => line.length > 0);
-  for (let idx = lines.length - 1; idx >= 0; idx -= 1) {
-    const parsed = parseStoragePaymentCronJobLine(lines[idx]);
+}
+function createOpenClawCliCronAdapter(homeDir) {
+  return {
+    add: async (job) => {
+      const { stdout } = await runOpenClawCli(
+        [
+          "cron",
+          "add",
+          "--name",
+          job.name,
+          "--cron",
+          job.schedule.expr,
+          "--tz",
+          job.schedule.tz,
+          "--session",
+          job.sessionTarget,
+          "--message",
+          job.payload.message,
+          "--announce",
+          "--description",
+          job.delivery.text,
+          "--json"
+        ],
+        homeDir
+      );
+      const payload = parseOpenClawCliJson(stdout, "cron add");
+      const createdIdRaw = typeof payload.id === "string" ? payload.id : payload.jobId;
+      const createdId = typeof createdIdRaw === "string" ? createdIdRaw.trim() : "";
+      if (!createdId) {
+        throw new Error("openclaw cron add did not return a job id");
+      }
+      return { jobId: createdId };
+    },
+    remove: async (jobId) => {
+      const { stdout } = await runOpenClawCli(["cron", "rm", jobId, "--json"], homeDir);
+      const payload = parseOpenClawCliJson(stdout, "cron rm");
+      if (typeof payload.removed === "boolean") {
+        return payload.removed;
+      }
+      return true;
+    },
+    list: async () => {
+      const { stdout } = await runOpenClawCli(["cron", "list", "--all", "--json"], homeDir);
+      const payload = parseOpenClawCliJson(stdout, "cron list");
+      const jobsRaw = Array.isArray(payload.jobs) ? payload.jobs : [];
+      return jobsRaw.map((entry) => normalizeOpenClawCronJobForLookup(entry)).filter((entry) => entry !== null);
+    }
+  };
+}
+async function findCronJobInOpenClawCronJobsByObjectKey(objectKey, adapter) {
+  const cronJobs = await adapter.list();
+  for (let idx = cronJobs.length - 1; idx >= 0; idx -= 1) {
+    const cronJob = cronJobs[idx];
+    const parsed = parseStoragePaymentCronCommand(cronJob.message);
     if (parsed && parsed.objectKey === objectKey) {
       return {
-        cronId: parsed.cronId,
+        cronId: cronJob.jobId,
         objectId: parsed.objectId,
         objectKey: parsed.objectKey
       };
@@ -4364,8 +4589,7 @@ function buildStoragePaymentCronCommand(job) {
   return [
     "/mnemospark_cloud",
     "payment-settle",
-    "--quote-id",
-    quoteCronArgument(job.quoteId),
+    "--renewal",
     "--wallet-address",
     quoteCronArgument(job.walletAddress),
     "--object-id",
@@ -4376,57 +4600,67 @@ function buildStoragePaymentCronCommand(job) {
     quoteCronArgument(job.storagePrice)
   ].join(" ");
 }
-async function appendStoragePaymentCronJob(cronJob, homeDir) {
-  const cronTablePath = resolveCronTablePath(homeDir);
-  await mkdir5(dirname5(cronTablePath), { recursive: true });
-  await appendFile2(cronTablePath, `${JSON.stringify(cronJob)}
-`, "utf-8");
-  return cronTablePath;
-}
-async function removeStoragePaymentCronJob(cronId, homeDir) {
-  const cronTablePath = resolveCronTablePath(homeDir);
-  let content;
-  try {
-    content = await readFile3(cronTablePath, "utf-8");
-  } catch (error) {
-    if (error.code === "ENOENT") {
-      return false;
-    }
-    throw error;
+function parseStoragePaymentCronCommand(command) {
+  const objectIdMatch = command.match(/--object-id\s+("([^"\\]|\\.)*"|'([^'\\]|\\.)*'|\S+)/);
+  const objectKeyMatch = command.match(/--object-key\s+("([^"\\]|\\.)*"|'([^'\\]|\\.)*'|\S+)/);
+  if (!objectIdMatch || !objectKeyMatch) {
+    return null;
   }
-  const lines = content.split(/\r?\n/);
-  let removed = false;
-  const keptLines = [];
-  for (const line of lines) {
-    const trimmed = line.trim();
+  const parseToken = (token) => {
+    const trimmed = token.trim();
     if (!trimmed) {
-      continue;
+      return null;
     }
-    const parsed = parseStoragePaymentCronJobLine(trimmed);
-    if (parsed && parsed.cronId === cronId) {
-      removed = true;
-      continue;
+    if (trimmed.startsWith('"') && trimmed.endsWith('"')) {
+      try {
+        return JSON.parse(trimmed);
+      } catch {
+        return trimmed.slice(1, -1);
+      }
     }
-    keptLines.push(trimmed);
-  }
-  if (!removed) {
-    return false;
+    if (trimmed.startsWith("'") && trimmed.endsWith("'")) {
+      return trimmed.slice(1, -1);
+    }
+    return trimmed;
+  };
+  const objectId = parseToken(objectIdMatch[1] ?? "");
+  const objectKey = parseToken(objectKeyMatch[1] ?? "");
+  if (!objectId || !objectKey) {
+    return null;
   }
-  await mkdir5(dirname5(cronTablePath), { recursive: true });
-  const nextContent = keptLines.length > 0 ? `${keptLines.join("\n")}
-` : "";
-  await writeFile3(cronTablePath, nextContent, "utf-8");
-  return true;
+  return { objectId, objectKey };
+}
+async function appendStoragePaymentCronJob(cronJob, adapter) {
+  const openClawJob = {
+    jobId: cronJob.cronId,
+    name: "Mnemospark Monthly Renewal",
+    schedule: {
+      kind: "cron",
+      expr: PAYMENT_CRON_SCHEDULE,
+      tz: "UTC"
+    },
+    payload: {
+      kind: "agentTurn",
+      message: cronJob.command
+    },
+    sessionTarget: "isolated",
+    delivery: {
+      mode: "announce",
+      text: "Thank you for using mnemospark cloud storage. Your renewal has been processed."
+    }
+  };
+  return adapter.add(openClawJob);
 }
-async function createStoragePaymentCronJob(upload, storagePrice, homeDir, nowDateFn = () => /* @__PURE__ */ new Date()) {
-  const cronId = randomUUID3();
-  const createdAt = formatTimestamp(nowDateFn());
+async function removeStoragePaymentCronJob(cronId, adapter) {
+  return adapter.remove(cronId);
+}
+async function createStoragePaymentCronJob(upload, storagePrice, openClawCronAdapter, nowDateFn = () => /* @__PURE__ */ new Date()) {
+  const provisionalCronId = randomUUID3();
   const cronJob = {
-    cronId,
-    createdAt,
+    cronId: provisionalCronId,
+    createdAt: nowDateFn().toISOString(),
     schedule: PAYMENT_CRON_SCHEDULE,
     command: buildStoragePaymentCronCommand({
-      quoteId: upload.quote_id,
       walletAddress: upload.addr,
       objectId: upload.object_id,
       objectKey: upload.object_key,
@@ -4441,7 +4675,10 @@ async function createStoragePaymentCronJob(upload, storagePrice, homeDir, nowDat
     bucketName: upload.bucket_name,
     location: upload.location
   };
-  await appendStoragePaymentCronJob(cronJob, homeDir);
+  const created = await appendStoragePaymentCronJob(cronJob, openClawCronAdapter);
+  if (created.jobId?.trim()) {
+    cronJob.cronId = created.jobId.trim();
+  }
   return cronJob;
 }
 async function readWalletKeyIfPresent(walletPath) {
@@ -4571,13 +4808,32 @@ async function uploadPresignedObjectIfNeeded(uploadResponse, uploadMode, encrypt
     `Presigned upload failed with status ${firstAttempt.status}${details ? `: ${details}` : ""}`
   );
 }
-async function maybeCleanupLocalBackupArchive(archivePath) {
-  const flag = process.env.MNEMOSPARK_DELETE_BACKUP_AFTER_UPLOAD;
-  if (!flag) {
-    return;
+function envMeansExplicitRemoveOrKeep(value) {
+  if (value === void 0) {
+    return null;
+  }
+  const trimmed = value.trim();
+  if (!trimmed) {
+    return null;
   }
-  const normalized = flag.trim().toLowerCase();
-  if (normalized !== "1" && normalized !== "true" && normalized !== "yes" && normalized !== "y") {
+  const n = trimmed.toLowerCase();
+  if (n === "0" || n === "false" || n === "no" || n === "n") {
+    return false;
+  }
+  if (n === "1" || n === "true" || n === "yes" || n === "y") {
+    return true;
+  }
+  return null;
+}
+function shouldRemoveLocalBackupAfterUpload() {
+  const parsed = envMeansExplicitRemoveOrKeep(process.env.MNEMOSPARK_REMOVE_BACKUP_FILE);
+  if (parsed !== null) {
+    return parsed;
+  }
+  return true;
+}
+async function maybeCleanupLocalBackupArchive(archivePath) {
+  if (!shouldRemoveLocalBackupAfterUpload()) {
     return;
   }
   try {
@@ -4588,9 +4844,9 @@ async function maybeCleanupLocalBackupArchive(archivePath) {
 function formatStorageUploadUserMessage(upload, cronJobId) {
   const lsLine = `/mnemospark_cloud ls --wallet-address \`${upload.addr}\``;
   return [
-    `Your file \`${upload.object_id}\` with key \`${upload.object_key}\` has been stored using \`${upload.provider}\` in \`${upload.bucket_name}\` \`${upload.location}\``,
+    `Your file \`${upload.object_id}\` with key \`${upload.object_key}\` has been stored using \`${upload.provider}\` in folder \`${upload.bucket_name}\` in region \`${upload.location}\``,
     "",
-    `A cron job \`${cronJobId}\` has been configured to send payment monthly (on the 1st) for storage services. If payment is not sent, your \`${upload.object_id}\` will be deleted after the ${PAYMENT_DELETE_DEADLINE_DAYS}-day deadline (${PAYMENT_REMINDER_INTERVAL_DAYS}-day billing interval + 2-day grace period).`,
+    `A cron job \`${cronJobId}\` has been configured to send renewal payment monthly (1st of the month, UTC), matching backend calendar billing. The object is skipped for deletion in its first UTC calendar month after upload; after that, if renewal is missing for a month, housekeeping may remove the object shortly after the 3rd (UTC).`,
     "",
     "To view your cloud storage run the command:",
     "",
@@ -4643,32 +4899,40 @@ function extractLsErrorMessage(error) {
   }
   return null;
 }
-function formatPriceStorageUserMessage(quote) {
+function formatPriceStorageUserMessage(quote, localArchiveHint) {
   const uploadLine = `/mnemospark_cloud upload --quote-id \`${quote.quote_id}\` --wallet-address \`${quote.addr}\` --object-id \`${quote.object_id}\` --object-id-hash \`${quote.object_id_hash}\``;
-  return [
-    `Your storage quote \`${quote.quote_id}\`: storage price \`${quote.storage_price}\` for \`${quote.object_id}\` with file size \`${quote.object_size_gb}\` in \`${quote.provider}\` \`${quote.location}\`.`,
+  const lines = [
+    `Your storage quote \`${quote.quote_id}\`: storage price \`$${quote.storage_price}\` for file \`${quote.object_id}\` with file size \`${quote.object_size_gb}\` in \`${quote.provider}\` \`${quote.location}\`.`,
     "",
     "If you accept this quote, run:",
     "",
     uploadLine,
-    "",
-    QUOTE_VALIDITY_USER_NOTE
-  ].join("\n");
+    ""
+  ];
+  if (localArchiveHint?.trim()) {
+    lines.push(
+      `Local backup archive uses friendly name \`${localArchiveHint.trim()}\` (on-disk basename is sanitized).`,
+      ""
+    );
+  }
+  lines.push(QUOTE_VALIDITY_USER_NOTE);
+  return lines.join("\n");
 }
 function quoteLookupMatchesPriceStorageResponse(lookup, quote) {
   return lookup.quoteId === quote.quote_id && lookup.walletAddress.trim().toLowerCase() === quote.addr.trim().toLowerCase() && lookup.objectId === quote.object_id && lookup.objectIdHash.toLowerCase() === quote.object_id_hash.toLowerCase() && lookup.storagePrice === quote.storage_price && lookup.provider === quote.provider && lookup.location === quote.location;
 }
-function formatBackupSuccessUserMessage(result) {
+function formatBackupSuccessUserMessage(result, walletAddress, friendlyName) {
   const hash = result.objectIdHash.replace(/\s/g, "");
-  const priceStorageLine = `/mnemospark_cloud price-storage --wallet-address <wallet-address> --object-id \`${result.objectId}\` --object-id-hash \`${hash}\` --gb \`${result.objectSizeGb}\` --provider <provider> --region <region>`;
+  const priceStorageLine = `/mnemospark_cloud price-storage --wallet-address \`${walletAddress}\` --object-id \`${result.objectId}\` --object-id-hash \`${hash}\` --gb \`${result.objectSizeGb}\` --provider <provider> --region <region>`;
   return [
     `Backup archive: \`${result.archivePath}\``,
     "",
+    `friendly-name: ${friendlyName}`,
     `object-id: ${result.objectId}`,
     `object-id-hash: ${hash}`,
     `object-size: ${result.objectSizeGb}`,
     "",
-    "Next, request a storage quote. Replace `<wallet-address>`, `<provider>`, and `<region>` (one line):",
+    "Next, request a storage quote. Replace `<provider>` and `<region>` (one line):",
     "",
     priceStorageLine,
     "",
@@ -4804,6 +5068,9 @@ function createCloudCommand(options = {}) {
           requestStorageDeleteFn: options.requestStorageDeleteFn ?? requestStorageDeleteViaProxy,
           requestPaymentSettleViaProxyFn: options.requestPaymentSettleViaProxyFn ?? requestPaymentSettleViaProxy,
           mnemosparkHomeDir: options.mnemosparkHomeDir ?? options.backupOptions?.homeDir,
+          openClawCronAdapter: options.openClawCronAdapter ?? createOpenClawCliCronAdapter(
+            options.mnemosparkHomeDir ?? options.backupOptions?.homeDir
+          ),
           backupOptions: options.backupOptions,
           proxyQuoteOptions: options.proxyQuoteOptions,
           proxyUploadOptions: options.proxyUploadOptions,
@@ -4956,10 +5223,26 @@ function parseTransIdFromPaymentSettleBody(bodyText) {
     return null;
   }
 }
+function parseQuoteIdFromPaymentSettleBody(bodyText) {
+  const trimmed = bodyText.trim();
+  if (!trimmed.startsWith("{")) {
+    return null;
+  }
+  try {
+    const parsed = JSON.parse(trimmed);
+    const q = parsed.quote_id;
+    return typeof q === "string" && q.trim() ? q.trim() : null;
+  } catch {
+    return null;
+  }
+}
 async function resolveAmountForPaymentSettle(quoteId, storagePriceFromFlag, datastore) {
   if (storagePriceFromFlag !== void 0 && Number.isFinite(storagePriceFromFlag)) {
     return storagePriceFromFlag;
   }
+  if (!quoteId) {
+    return 0;
+  }
   const quoteLookup = await datastore.findQuoteById(quoteId);
   if (quoteLookup && Number.isFinite(quoteLookup.storagePrice)) {
     return quoteLookup.storagePrice;
@@ -4970,6 +5253,20 @@ async function resolveAmountForPaymentSettle(quoteId, storagePriceFromFlag, data
   }
   return 0;
 }
+async function resolveCronRowForPaymentSettle(req, datastore) {
+  if (req.renewal) {
+    const key = req.object_key?.trim();
+    if (!key) {
+      return null;
+    }
+    return datastore.findCronJobRowByObjectKey(key);
+  }
+  const qid = req.quote_id?.trim();
+  if (!qid) {
+    return null;
+  }
+  return datastore.findCronByQuoteId(qid);
+}
 async function emitPaymentSettleClientObservationBestEffort(params) {
   try {
     const {
@@ -5069,6 +5366,7 @@ async function runCloudCommandHandler(ctx, options, executionContext = {}) {
   const requestStorageDownload = options.requestStorageDownloadFn;
   const requestStorageDelete = options.requestStorageDeleteFn;
   const requestPaymentSettleViaProxy2 = options.requestPaymentSettleViaProxyFn;
+  const openClawCronAdapter = options.openClawCronAdapter;
   const subagentOrchestrator = options.subagentOrchestrator;
   if (parsed.mode === "help" || parsed.mode === "unknown") {
     return {
@@ -5094,6 +5392,12 @@ async function runCloudCommandHandler(ctx, options, executionContext = {}) {
       isError: true
     };
   }
+  if (parsed.mode === "backup-invalid-name") {
+    return {
+      text: `Cannot build storage object: required arguments are ${REQUIRED_BACKUP}.`,
+      isError: true
+    };
+  }
   if (parsed.mode === "upload-invalid") {
     return {
       text: `Cannot upload storage object: required arguments are ${REQUIRED_UPLOAD}.`,
@@ -5108,7 +5412,7 @@ async function runCloudCommandHandler(ctx, options, executionContext = {}) {
   }
   if (parsed.mode === "payment-settle-invalid") {
     return {
-      text: `Cannot settle payment: required arguments are ${REQUIRED_PAYMENT_SETTLE}. Optional: --object-id, --object-key, --storage-price.`,
+      text: `Cannot settle payment: required arguments are ${REQUIRED_PAYMENT_SETTLE}. Optional: --object-id, --storage-price.`,
       isError: true
     };
   }
@@ -5276,10 +5580,11 @@ async function runCloudCommandHandler(ctx, options, executionContext = {}) {
     const settleFetch = createPayment(walletKey).fetch;
     const objectId = req.object_id;
     const objectKey = req.object_key;
+    const logQuoteId = req.quote_id?.trim() || (req.renewal && objectKey?.trim() ? `renewal:${objectKey.trim()}` : "");
     await emitPaymentSettleClientObservationBestEffort({
       phase: "start",
       correlation,
-      quoteId: req.quote_id,
+      quoteId: logQuoteId,
       walletAddress: req.wallet_address,
       objectId,
       objectKey,
@@ -5287,10 +5592,12 @@ async function runCloudCommandHandler(ctx, options, executionContext = {}) {
     });
     let settleResult;
     try {
-      settleResult = await requestPaymentSettleViaProxy2(req.quote_id, req.wallet_address, {
+      settleResult = await requestPaymentSettleViaProxy2(req.quote_id ?? "", req.wallet_address, {
         ...options.proxySettleOptions,
         correlation,
-        fetchImpl: (input, init) => settleFetch(input, init)
+        fetchImpl: (input, init) => settleFetch(input, init),
+        renewal: req.renewal === true,
+        objectKey: req.object_key
       });
     } catch (err) {
       const amountErr = await resolveAmountForPaymentSettle(
@@ -5299,7 +5606,7 @@ async function runCloudCommandHandler(ctx, options, executionContext = {}) {
         datastore
       );
       await datastore.upsertPayment({
-        quote_id: req.quote_id,
+        quote_id: logQuoteId || req.quote_id?.trim() || "payment-settle-error",
         wallet_address: req.wallet_address,
         trans_id: null,
         amount: amountErr,
@@ -5307,7 +5614,7 @@ async function runCloudCommandHandler(ctx, options, executionContext = {}) {
         status: "settle_failed",
         settled_at: null
       });
-      const cronErr = await datastore.findCronByQuoteId(req.quote_id);
+      const cronErr = await resolveCronRowForPaymentSettle(req, datastore);
       if (cronErr) {
         await datastore.upsertCronJob({ ...cronErr, status: "active" });
       }
@@ -5315,7 +5622,7 @@ async function runCloudCommandHandler(ctx, options, executionContext = {}) {
       await emitPaymentSettleClientObservationBestEffort({
         phase: "result",
         correlation,
-        quoteId: req.quote_id,
+        quoteId: logQuoteId,
         walletAddress: req.wallet_address,
         objectId,
         objectKey,
@@ -5324,11 +5631,17 @@ async function runCloudCommandHandler(ctx, options, executionContext = {}) {
       });
       return { text: `Payment settle failed: ${msg}`, isError: true };
     }
-    const amount = await resolveAmountForPaymentSettle(req.quote_id, req.storage_price, datastore);
+    const ledgerQuoteIdFromBody = parseQuoteIdFromPaymentSettleBody(settleResult.bodyText ?? "");
+    const ledgerQuoteId = ledgerQuoteIdFromBody || req.quote_id?.trim() || logQuoteId;
+    const amount = await resolveAmountForPaymentSettle(
+      req.renewal ? void 0 : req.quote_id,
+      req.storage_price,
+      datastore
+    );
     const transId = settleResult.status === 200 ? parseTransIdFromPaymentSettleBody(settleResult.bodyText ?? "") : null;
     if (settleResult.status === 200) {
       await datastore.upsertPayment({
-        quote_id: req.quote_id,
+        quote_id: ledgerQuoteId,
         wallet_address: req.wallet_address,
         trans_id: transId,
         amount,
@@ -5336,14 +5649,14 @@ async function runCloudCommandHandler(ctx, options, executionContext = {}) {
         status: "settled",
         settled_at: (/* @__PURE__ */ new Date()).toISOString()
       });
-      const cronRow = await datastore.findCronByQuoteId(req.quote_id);
+      const cronRow = await resolveCronRowForPaymentSettle(req, datastore);
       if (cronRow) {
         await datastore.upsertCronJob({ ...cronRow, status: "active" });
       }
       await emitPaymentSettleClientObservationBestEffort({
         phase: "result",
         correlation,
-        quoteId: req.quote_id,
+        quoteId: ledgerQuoteId,
         walletAddress: req.wallet_address,
         objectId,
         objectKey,
@@ -5351,12 +5664,13 @@ async function runCloudCommandHandler(ctx, options, executionContext = {}) {
         outcomeStatus: "succeeded",
         homeDir: mnemosparkHomeDir
       });
+      const label = req.renewal ? `object ${req.object_key}` : `quote ${req.quote_id}`;
       return {
-        text: transId ? `Payment settled for quote ${req.quote_id} (trans_id: ${transId}).` : `Payment settled for quote ${req.quote_id}.`
+        text: transId ? `Payment settled for ${label} (trans_id: ${transId}).` : `Payment settled for ${label}.`
       };
     }
     await datastore.upsertPayment({
-      quote_id: req.quote_id,
+      quote_id: ledgerQuoteId,
       wallet_address: req.wallet_address,
       trans_id: transId,
       amount,
@@ -5364,14 +5678,14 @@ async function runCloudCommandHandler(ctx, options, executionContext = {}) {
       status: "settle_failed",
       settled_at: null
     });
-    const cronRowFailed = await datastore.findCronByQuoteId(req.quote_id);
+    const cronRowFailed = await resolveCronRowForPaymentSettle(req, datastore);
     if (cronRowFailed) {
       await datastore.upsertCronJob({ ...cronRowFailed, status: "active" });
     }
     await emitPaymentSettleClientObservationBestEffort({
       phase: "result",
       correlation,
-      quoteId: req.quote_id,
+      quoteId: ledgerQuoteId,
       walletAddress: req.wallet_address,
       objectId,
       objectKey,
@@ -5720,8 +6034,38 @@ operation-id: ${operationId}`,
     };
   }
   if (parsed.mode === "backup") {
+    const backupPlatform = options.backupOptions?.platform ?? process.platform;
+    if (!SUPPORTED_BACKUP_PLATFORMS.has(backupPlatform)) {
+      return {
+        text: "Cloud backup is only supported on macOS and Linux.",
+        isError: true
+      };
+    }
     try {
-      const result = await backupBuilder(parsed.backupTarget, options.backupOptions);
+      let walletAddress;
+      try {
+        const walletKey = await resolveWalletKey(mnemosparkHomeDir);
+        walletAddress = privateKeyToAccount5(walletKey).address;
+      } catch (err) {
+        const message = err instanceof Error ? err.message : typeof err === "string" ? err : String(err);
+        return {
+          text: message.trim() || "No mnemospark wallet found.",
+          isError: true
+        };
+      }
+      let archiveBasename;
+      try {
+        archiveBasename = sanitizeFriendlyNameForLocalBasename(parsed.friendlyName);
+      } catch {
+        return {
+          text: "Cannot build storage object: invalid --name for local file path (use a non-empty name without reserved path segments).",
+          isError: true
+        };
+      }
+      const result = await backupBuilder(parsed.backupTarget, {
+        ...options.backupOptions,
+        archiveBasename
+      });
       await emitCloudEventBestEffort(
         "backup.completed",
         {
@@ -5729,7 +6073,7 @@ operation-id: ${operationId}`,
           object_id: result.objectId,
           status: "succeeded",
           details: {
-            friendly_name: parsed.friendlyName ?? basename2(parsed.backupTarget),
+            friendly_name: parsed.friendlyName,
             archive_path: result.archivePath,
             object_id_hash: result.objectIdHash.replace(/\s/g, ""),
             object_size_gb: result.objectSizeGb
@@ -5740,7 +6084,7 @@ operation-id: ${operationId}`,
       await datastore.upsertObject({
         object_id: result.objectId,
         object_key: null,
-        wallet_address: "unknown",
+        wallet_address: walletAddress,
         quote_id: null,
         provider: null,
         bucket_name: null,
@@ -5748,23 +6092,20 @@ operation-id: ${operationId}`,
         sha256: result.objectIdHash,
         status: "backed_up"
       });
-      const friendlyName = parsed.friendlyName?.trim() || basename2(parsed.backupTarget);
-      if (friendlyName) {
-        await datastore.upsertFriendlyName({
-          friendly_name: friendlyName,
-          object_id: result.objectId,
-          object_key: null,
-          quote_id: null,
-          wallet_address: "unknown"
-        });
-      }
+      await datastore.upsertFriendlyName({
+        friendly_name: parsed.friendlyName,
+        object_id: result.objectId,
+        object_key: null,
+        quote_id: null,
+        wallet_address: walletAddress
+      });
       return {
-        text: formatBackupSuccessUserMessage(result)
+        text: formatBackupSuccessUserMessage(result, walletAddress, parsed.friendlyName)
       };
     } catch (err) {
-      if (err instanceof UnsupportedBackupPlatformError) {
+      if (err instanceof Error && err.message.includes("already exists")) {
         return {
-          text: "Cloud backup is only supported on macOS and Linux.",
+          text: err.message,
           isError: true
         };
       }
@@ -5820,8 +6161,14 @@ operation-id: ${operationId}`,
         },
         mnemosparkHomeDir
       );
+      let friendlyForQuote = null;
+      try {
+        friendlyForQuote = await datastore.findLatestFriendlyNameForObjectId(quote.object_id);
+      } catch {
+        friendlyForQuote = null;
+      }
       return {
-        text: formatPriceStorageUserMessage(quote)
+        text: formatPriceStorageUserMessage(quote, friendlyForQuote)
       };
     } catch (err) {
       await emitCloudEventBestEffort(
@@ -5861,10 +6208,33 @@ operation-id: ${operationId}`,
           isError: true
         };
       }
-      const archivePath = join8(
-        options.backupOptions?.tmpDir ?? DEFAULT_BACKUP_DIR,
+      const backupDir = options.backupOptions?.tmpDir ?? DEFAULT_BACKUP_DIR;
+      const dbFriendly = await datastore.findLatestFriendlyNameForObjectId(
         parsed.uploadRequest.object_id
       );
+      if (!dbFriendly?.trim()) {
+        return {
+          text: "Cannot upload storage object: no friendly name in local SQLite for this object-id. Run /mnemospark_cloud backup with --name first.",
+          isError: true
+        };
+      }
+      if (parsed.friendlyName?.trim()) {
+        if (parsed.friendlyName.trim() !== dbFriendly.trim()) {
+          return {
+            text: "Cannot upload storage object: --name does not match the friendly name stored in local SQLite for this object-id.",
+            isError: true
+          };
+        }
+      }
+      const resolvedArchive = await resolveLocalUploadArchivePath(
+        backupDir,
+        parsed.uploadRequest.object_id,
+        dbFriendly
+      );
+      if (!resolvedArchive.ok) {
+        return { text: resolvedArchive.message, isError: true };
+      }
+      const archivePath = resolvedArchive.archivePath;
       let archiveStats;
       try {
         archiveStats = await stat2(archivePath);
@@ -5969,7 +6339,7 @@ operation-id: ${operationId}`,
       const cronJob = await createStoragePaymentCronJob(
         finalizedUploadResponse,
         cronStoragePrice,
-        mnemosparkHomeDir,
+        openClawCronAdapter,
         nowDateFn
       );
       await datastore.upsertObject({
@@ -6001,45 +6371,43 @@ operation-id: ${operationId}`,
         command: cronJob.command,
         status: "active"
       });
-      if (parsed.friendlyName?.trim()) {
-        const normalizedFriendlyName = parsed.friendlyName.trim();
-        await datastore.upsertFriendlyName({
-          friendly_name: normalizedFriendlyName,
-          object_id: finalizedUploadResponse.object_id,
-          object_key: finalizedUploadResponse.object_key,
-          quote_id: finalizedUploadResponse.quote_id,
-          wallet_address: finalizedUploadResponse.addr
+      const normalizedFriendlyName = dbFriendly.trim();
+      await datastore.upsertFriendlyName({
+        friendly_name: normalizedFriendlyName,
+        object_id: finalizedUploadResponse.object_id,
+        object_key: finalizedUploadResponse.object_key,
+        quote_id: finalizedUploadResponse.quote_id,
+        wallet_address: finalizedUploadResponse.addr
+      });
+      let friendlyNameVerified = false;
+      try {
+        const readBack = await datastore.resolveFriendlyName({
+          walletAddress: finalizedUploadResponse.addr,
+          friendlyName: normalizedFriendlyName,
+          latest: true
         });
-        let friendlyNameVerified = false;
-        try {
-          const readBack = await datastore.resolveFriendlyName({
-            walletAddress: finalizedUploadResponse.addr,
-            friendlyName: normalizedFriendlyName,
-            latest: true
-          });
-          friendlyNameVerified = Boolean(readBack?.objectKey) && readBack?.objectKey === finalizedUploadResponse.object_key;
-        } catch {
-          friendlyNameVerified = false;
-        }
-        if (!friendlyNameVerified) {
-          const warning = "SQLite friendly-name write verification failed; --name lookups may not resolve until SQLite is healthy.";
-          await emitCloudEventBestEffort(
-            "friendly_name.write_verification_failed",
-            {
-              operation_id: uploadCorrelation.operationId,
-              trace_id: uploadCorrelation.traceId,
-              wallet_address: finalizedUploadResponse.addr,
-              object_id: finalizedUploadResponse.object_id,
-              object_key: finalizedUploadResponse.object_key,
-              quote_id: finalizedUploadResponse.quote_id,
-              friendly_name: normalizedFriendlyName,
-              warning
-            },
-            mnemosparkHomeDir
-          );
-          if (process.env.MNEMOSPARK_SQLITE_STRICT === "1") {
-            throw new Error(warning);
-          }
+        friendlyNameVerified = Boolean(readBack?.objectKey) && readBack?.objectKey === finalizedUploadResponse.object_key;
+      } catch {
+        friendlyNameVerified = false;
+      }
+      if (!friendlyNameVerified) {
+        const warning = "SQLite friendly-name write verification failed; --name lookups may not resolve until SQLite is healthy.";
+        await emitCloudEventBestEffort(
+          "friendly_name.write_verification_failed",
+          {
+            operation_id: uploadCorrelation.operationId,
+            trace_id: uploadCorrelation.traceId,
+            wallet_address: finalizedUploadResponse.addr,
+            object_id: finalizedUploadResponse.object_id,
+            object_key: finalizedUploadResponse.object_key,
+            quote_id: finalizedUploadResponse.quote_id,
+            friendly_name: normalizedFriendlyName,
+            warning
+          },
+          mnemosparkHomeDir
+        );
+        if (process.env.MNEMOSPARK_SQLITE_STRICT === "1") {
+          throw new Error(warning);
         }
       }
       await emitCloudEventBestEffort(
@@ -6202,10 +6570,27 @@ operation-id: ${operationId}`,
       error_code: null,
       error_message: null
     });
+    let downloadLocalBasename;
+    try {
+      const friendly = await datastore.findLatestFriendlyNameForObjectKey(
+        resolvedRequest.wallet_address,
+        resolvedRequest.object_key
+      );
+      if (friendly?.trim()) {
+        try {
+          downloadLocalBasename = sanitizeFriendlyNameForLocalBasename(friendly);
+        } catch {
+          downloadLocalBasename = void 0;
+        }
+      }
+    } catch {
+      downloadLocalBasename = void 0;
+    }
     try {
       const downloadResult = await requestStorageDownload(resolvedRequest, {
         ...options.proxyStorageOptions,
-        correlation
+        correlation,
+        ...downloadLocalBasename ? { downloadLocalBasename } : {}
       });
       if (!downloadResult.success) {
         throw new Error("download failed");
@@ -6318,15 +6703,15 @@ operation-id: ${operationId}`,
         };
       }
       if (!cronEntry) {
-        cronEntry = await findCronJobInCrontabByObjectKey(
+        cronEntry = await findCronJobInOpenClawCronJobsByObjectKey(
           resolvedRequest.object_key,
-          mnemosparkHomeDir
+          openClawCronAdapter
         );
       }
       if (cronEntry) {
         const fileCronDeleted = await removeStoragePaymentCronJob(
           cronEntry.cronId,
-          mnemosparkHomeDir
+          openClawCronAdapter
         );
         const dbCronDeleted = await datastore.removeCronJob(cronEntry.cronId);
         cronDeleted = fileCronDeleted || dbCronDeleted;