mnemospark 0.1.21 → 0.2.0

package/dist/cli.js

@@ -282,6 +282,21 @@ async function createWalletSignatureHeaderValue(method, path, walletAddress, wal
   return encodeBase64Json(headerEnvelope);
 }
 
+// src/cloud-correlation.ts
+var MNEMOSPARK_TRACE_ID_HEADER = "X-Mnemospark-Trace-Id";
+var MNEMOSPARK_OPERATION_ID_HEADER = "X-Mnemospark-Operation-Id";
+function applyCorrelationHeaders(headers, correlation) {
+  const traceId = correlation?.traceId?.trim();
+  if (traceId) {
+    headers[MNEMOSPARK_TRACE_ID_HEADER] = traceId;
+  }
+  const operationId = correlation?.operationId?.trim();
+  if (operationId) {
+    headers[MNEMOSPARK_OPERATION_ID_HEADER] = operationId;
+  }
+  return headers;
+}
+
 // src/cloud-utils.ts
 function normalizeBaseUrl(baseUrl) {
   return baseUrl.replace(/\/+$/, "");
@@ -511,9 +526,12 @@ async function requestPriceStorageViaProxy(request, options = {}) {
   );
   const response = await fetchImpl(`${baseUrl}${PRICE_STORAGE_PROXY_PATH}`, {
     method: "POST",
-    headers: {
-      "Content-Type": "application/json"
-    },
+    headers: applyCorrelationHeaders(
+      {
+        "Content-Type": "application/json"
+      },
+      options.correlation
+    ),
     body: JSON.stringify(request)
   });
   const responseBody = await response.text();
@@ -538,6 +556,7 @@ async function requestStorageUploadViaProxy(request, options = {}) {
   const requestHeaders = {
     "Content-Type": "application/json"
   };
+  applyCorrelationHeaders(requestHeaders, options.correlation);
   if (options.idempotencyKey && options.idempotencyKey.trim().length > 0) {
     requestHeaders["Idempotency-Key"] = options.idempotencyKey.trim();
   }
@@ -619,9 +638,12 @@ async function requestStorageUploadConfirmViaProxy(request, options = {}) {
   );
   const response = await fetchImpl(`${baseUrl}${UPLOAD_CONFIRM_PROXY_PATH}`, {
     method: "POST",
-    headers: {
-      "Content-Type": "application/json"
-    },
+    headers: applyCorrelationHeaders(
+      {
+        "Content-Type": "application/json"
+      },
+      options.correlation
+    ),
     body: JSON.stringify(request)
   });
   const responseBody = await response.text();
@@ -736,7 +758,7 @@ async function requestPaymentSettleViaProxy(quoteId, walletAddress, options = {}
   }
   const response = await fetchImpl(targetUrl, {
     method: "POST",
-    headers: { "Content-Type": "application/json" },
+    headers: applyCorrelationHeaders({ "Content-Type": "application/json" }, options.correlation),
     body: JSON.stringify(requestBody)
   });
   return {
@@ -1220,9 +1242,12 @@ async function requestJsonViaProxy(proxyPath, request, parser, options = {}) {
   );
   const response = await fetchImpl(`${baseUrl}${proxyPath}`, {
     method: "POST",
-    headers: {
-      "Content-Type": "application/json"
-    },
+    headers: applyCorrelationHeaders(
+      {
+        "Content-Type": "application/json"
+      },
+      options.correlation
+    ),
     body: JSON.stringify(request)
   });
   const bodyText = await response.text();
@@ -1546,6 +1571,20 @@ function emitProxyEvent(eventType, status, correlation, details = {}) {
     details
   }).catch(() => void 0);
 }
+function createProxyCorrelation(headers) {
+  const traceId = readHeaderValue(headers[MNEMOSPARK_TRACE_ID_HEADER.toLowerCase()]) ?? randomUUID();
+  const operationId = readHeaderValue(
+    headers[MNEMOSPARK_OPERATION_ID_HEADER.toLowerCase()] ?? headers["idempotency-key"]
+  ) ?? randomUUID();
+  return { trace_id: traceId, operation_id: operationId };
+}
+function emitProxyTerminalFromStatus(correlation, statusCode, details = {}) {
+  if (statusCode >= 200 && statusCode < 300) {
+    emitProxyEvent("terminal.success", "success", correlation, { status: statusCode, ...details });
+    return;
+  }
+  emitProxyEvent("terminal.failure", "failure", correlation, { status: statusCode, ...details });
+}
 function isAlreadySettledConflict(status, bodyText) {
   if (status !== 409) {
     return false;
@@ -1670,10 +1709,7 @@ async function startProxy(options) {
       console.error(`[mnemospark] Response stream error: ${err.message}`);
     });
     if (req.method === "POST" && matchesProxyPath(req.url, PRICE_STORAGE_PROXY_PATH)) {
-      const correlation = {
-        trace_id: randomUUID(),
-        operation_id: randomUUID()
-      };
+      const correlation = createProxyCorrelation(req.headers);
       logProxyEvent("info", "proxy_price_storage_received");
       emitProxyEvent("request.received", "start", correlation, { path: PRICE_STORAGE_PROXY_PATH });
       try {
@@ -1682,15 +1718,17 @@ async function startProxy(options) {
           payload = await readProxyJsonBody(req);
         } catch {
           logProxyEvent("warn", "proxy_price_storage_invalid_json");
+          emitProxyTerminalFromStatus(correlation, 400, { reason: "invalid_json" });
           sendJson(res, 400, {
             error: "Bad request",
-            message: "Invalid JSON body for /mnemospark-cloud price-storage"
+            message: "Invalid JSON body for /mnemospark_cloud price-storage"
           });
           return;
         }
         const requestPayload = parsePriceStorageQuoteRequest(payload);
         if (!requestPayload) {
           logProxyEvent("warn", "proxy_price_storage_missing_fields");
+          emitProxyTerminalFromStatus(correlation, 400, { reason: "missing_fields" });
           sendJson(res, 400, {
             error: "Bad request",
             message: "Missing required fields: wallet_address, object_id, object_id_hash, gb, provider, region"
@@ -1709,6 +1747,7 @@ async function startProxy(options) {
           logProxyEvent("warn", "proxy_price_storage_wallet_signature_missing");
           res.writeHead(400, { "Content-Type": "application/json" });
           res.end(createWalletRequiredBody());
+          emitProxyTerminalFromStatus(correlation, 400, { reason: "wallet_signature_missing" });
           return;
         }
         const backendResponse = await forwardPriceStorageToBackend(requestPayload, {
@@ -1734,14 +1773,13 @@ async function startProxy(options) {
           });
           res.writeHead(authFailure.status, responseHeaders2);
           res.end(authFailure.bodyText);
+          emitProxyTerminalFromStatus(correlation, authFailure.status, { reason: "auth_failure" });
           return;
         }
         const responseHeaders = createBackendForwardHeaders(backendResponse);
         res.writeHead(backendResponse.status, responseHeaders);
         res.end(backendResponse.bodyText);
-        emitProxyEvent("terminal.success", "success", correlation, {
-          status: backendResponse.status
-        });
+        emitProxyTerminalFromStatus(correlation, backendResponse.status);
       } catch (err) {
         emitProxyEvent("terminal.failure", "failure", correlation, {
           error: err instanceof Error ? err.message : String(err)
@@ -1751,16 +1789,13 @@ async function startProxy(options) {
         });
         sendJson(res, 502, {
           error: "proxy_error",
-          message: `Failed to forward /mnemospark-cloud price-storage: ${err instanceof Error ? err.message : String(err)}`
+          message: `Failed to forward /mnemospark_cloud price-storage: ${err instanceof Error ? err.message : String(err)}`
         });
       }
       return;
     }
     if (req.method === "POST" && matchesProxyPath(req.url, PAYMENT_SETTLE_PROXY_PATH)) {
-      const correlation = {
-        trace_id: randomUUID(),
-        operation_id: randomUUID()
-      };
+      const correlation = createProxyCorrelation(req.headers);
       logProxyEvent("info", "proxy_payment_settle_received");
       emitProxyEvent("request.received", "start", correlation, { path: PAYMENT_SETTLE_PROXY_PATH });
       try {
@@ -1769,6 +1804,7 @@ async function startProxy(options) {
           payload = await readProxyJsonBody(req);
         } catch {
           logProxyEvent("warn", "proxy_payment_settle_invalid_json");
+          emitProxyTerminalFromStatus(correlation, 400, { reason: "invalid_json" });
           sendJson(res, 400, {
             error: "Bad request",
             message: "Invalid JSON body for /mnemospark/payment/settle"
@@ -1782,6 +1818,7 @@ async function startProxy(options) {
         const inlinePaymentAuthorization = record?.payment_authorization;
         if (!quoteId || !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"
@@ -1790,6 +1827,7 @@ async function startProxy(options) {
         }
         if (inlinePayment !== void 0 && (inlinePayment === null || typeof inlinePayment !== "object" || Array.isArray(inlinePayment))) {
           logProxyEvent("warn", "proxy_payment_settle_invalid_payment_shape");
+          emitProxyTerminalFromStatus(correlation, 400, { reason: "invalid_payment_shape" });
           sendJson(res, 400, {
             error: "Bad request",
             message: "Invalid field: payment must be an object when provided"
@@ -1798,6 +1836,9 @@ async function startProxy(options) {
         }
         if (inlinePaymentAuthorization !== void 0 && !(typeof inlinePaymentAuthorization === "string" || inlinePaymentAuthorization !== null && typeof inlinePaymentAuthorization === "object" && !Array.isArray(inlinePaymentAuthorization))) {
           logProxyEvent("warn", "proxy_payment_settle_invalid_payment_authorization_shape");
+          emitProxyTerminalFromStatus(correlation, 400, {
+            reason: "invalid_payment_authorization_shape"
+          });
           sendJson(res, 400, {
             error: "Bad request",
             message: "Invalid field: payment_authorization must be an object or string when provided"
@@ -1809,6 +1850,7 @@ async function startProxy(options) {
             request_wallet: walletAddress,
             proxy_wallet: account.address
           });
+          emitProxyTerminalFromStatus(correlation, 403, { reason: "wallet_mismatch" });
           sendJson(res, 403, {
             error: "wallet_proof_invalid",
             message: "wallet proof invalid"
@@ -1824,6 +1866,7 @@ async function startProxy(options) {
           logProxyEvent("warn", "proxy_payment_settle_wallet_signature_missing");
           res.writeHead(400, { "Content-Type": "application/json" });
           res.end(createWalletRequiredBody());
+          emitProxyTerminalFromStatus(correlation, 400, { reason: "wallet_signature_missing" });
           return;
         }
         correlation.quote_id = quoteId;
@@ -1858,14 +1901,13 @@ async function startProxy(options) {
           });
           res.writeHead(authFailure.status, responseHeaders2);
           res.end(authFailure.bodyText);
+          emitProxyTerminalFromStatus(correlation, authFailure.status, { reason: "auth_failure" });
           return;
         }
         const responseHeaders = createBackendForwardHeaders(backendResponse);
         res.writeHead(backendResponse.status, responseHeaders);
         res.end(backendResponse.bodyText);
-        emitProxyEvent("terminal.success", "success", correlation, {
-          status: backendResponse.status
-        });
+        emitProxyTerminalFromStatus(correlation, backendResponse.status);
       } catch (err) {
         emitProxyEvent("terminal.failure", "failure", correlation, {
           error: err instanceof Error ? err.message : String(err)
@@ -1881,10 +1923,7 @@ async function startProxy(options) {
       return;
     }
     if (req.method === "POST" && matchesProxyPath(req.url, UPLOAD_PROXY_PATH)) {
-      const correlation = {
-        trace_id: randomUUID(),
-        operation_id: randomUUID()
-      };
+      const correlation = createProxyCorrelation(req.headers);
       logProxyEvent("info", "proxy_upload_received");
       emitProxyEvent("request.received", "start", correlation, { path: UPLOAD_PROXY_PATH });
       try {
@@ -1893,15 +1932,17 @@ async function startProxy(options) {
           payload = await readProxyJsonBody(req);
         } catch {
           logProxyEvent("warn", "proxy_upload_invalid_json");
+          emitProxyTerminalFromStatus(correlation, 400, { reason: "invalid_json" });
           sendJson(res, 400, {
             error: "Bad request",
-            message: "Invalid JSON body for /mnemospark-cloud upload"
+            message: "Invalid JSON body for /mnemospark_cloud upload"
           });
           return;
         }
         const requestPayload = parseStorageUploadRequest(payload);
         if (!requestPayload) {
           logProxyEvent("warn", "proxy_upload_missing_fields");
+          emitProxyTerminalFromStatus(correlation, 400, { reason: "missing_fields" });
           sendJson(res, 400, {
             error: "Bad request",
             message: "Missing required fields: quote_id, wallet_address, object_id, object_id_hash, quoted_storage_price, payload"
@@ -1911,12 +1952,12 @@ async function startProxy(options) {
         correlation.quote_id = requestPayload.quote_id;
         correlation.wallet_address = requestPayload.wallet_address;
         correlation.object_id = requestPayload.object_id;
-        emitProxyEvent("storage.call", "start", correlation, { target: "storage/upload" });
         if (requestPayload.wallet_address.toLowerCase() !== proxyWalletAddressLower) {
           logProxyEvent("warn", "proxy_upload_wallet_mismatch", {
             request_wallet: requestPayload.wallet_address,
             proxy_wallet: account.address
           });
+          emitProxyTerminalFromStatus(correlation, 403, { reason: "wallet_mismatch" });
           sendJson(res, 403, {
             error: "wallet_proof_invalid",
             message: "wallet proof invalid"
@@ -1932,6 +1973,7 @@ async function startProxy(options) {
           logProxyEvent("warn", "proxy_upload_wallet_signature_missing");
           res.writeHead(400, { "Content-Type": "application/json" });
           res.end(createWalletRequiredBody());
+          emitProxyTerminalFromStatus(correlation, 400, { reason: "wallet_signature_missing" });
           return;
         }
         const requiredMicros = BigInt(
@@ -1951,11 +1993,12 @@ async function startProxy(options) {
             requiredUSD,
             walletAddress: requestPayload.wallet_address
           });
+          emitProxyTerminalFromStatus(correlation, 400, { reason: "insufficient_balance" });
           sendJson(res, 400, {
             error: "insufficient_balance",
             message: `Insufficient USDC balance. Current: ${sufficiency.info.balanceUSD}, Required: ${requiredUSD}`,
             wallet: requestPayload.wallet_address,
-            help: `Fund wallet ${requestPayload.wallet_address} on Base before running /mnemospark-cloud upload`
+            help: `Fund wallet ${requestPayload.wallet_address} on Base before running /mnemospark_cloud upload`
           });
           return;
         }
@@ -1978,6 +2021,7 @@ async function startProxy(options) {
           logProxyEvent("warn", "proxy_upload_settle_signature_missing");
           res.writeHead(400, { "Content-Type": "application/json" });
           res.end(createWalletRequiredBody());
+          emitProxyTerminalFromStatus(correlation, 400, { reason: "settle_signature_missing" });
           return;
         }
         const uploadPaymentFetch = createPaymentFetch(walletPrivateKey).fetch;
@@ -2007,6 +2051,9 @@ async function startProxy(options) {
           });
           res.writeHead(settleResponse.status, responseHeaders2);
           res.end(settleResponse.bodyText);
+          emitProxyTerminalFromStatus(correlation, settleResponse.status, {
+            reason: "settle_failed"
+          });
           return;
         }
         if (settledAlready) {
@@ -2018,6 +2065,7 @@ async function startProxy(options) {
             status: settleResponse.status
           });
         }
+        emitProxyEvent("storage.call", "start", correlation, { target: "storage/upload" });
         const backendResponse = await forwardStorageUploadToBackend(requestPayload, {
           backendBaseUrl: MNEMOSPARK_BACKEND_API_BASE_URL,
           walletSignature,
@@ -2042,14 +2090,13 @@ async function startProxy(options) {
           });
           res.writeHead(authFailure.status, responseHeaders2);
           res.end(authFailure.bodyText);
+          emitProxyTerminalFromStatus(correlation, authFailure.status, { reason: "auth_failure" });
           return;
         }
         const responseHeaders = createBackendForwardHeaders(backendResponse);
         res.writeHead(backendResponse.status, responseHeaders);
         res.end(backendResponse.bodyText);
-        emitProxyEvent("terminal.success", "success", correlation, {
-          status: backendResponse.status
-        });
+        emitProxyTerminalFromStatus(correlation, backendResponse.status);
       } catch (err) {
         emitProxyEvent("terminal.failure", "failure", correlation, {
           error: err instanceof Error ? err.message : String(err)
@@ -2059,39 +2106,47 @@ async function startProxy(options) {
         });
         sendJson(res, 502, {
           error: "proxy_error",
-          message: `Failed to forward /mnemospark-cloud upload: ${err instanceof Error ? err.message : String(err)}`
+          message: `Failed to forward /mnemospark_cloud upload: ${err instanceof Error ? err.message : String(err)}`
         });
       }
       return;
     }
     if (req.method === "POST" && matchesProxyPath(req.url, UPLOAD_CONFIRM_PROXY_PATH)) {
+      const correlation = createProxyCorrelation(req.headers);
       logProxyEvent("info", "proxy_upload_confirm_received");
+      emitProxyEvent("request.received", "start", correlation, { path: UPLOAD_CONFIRM_PROXY_PATH });
       try {
         let payload;
         try {
           payload = await readProxyJsonBody(req);
         } catch {
           logProxyEvent("warn", "proxy_upload_confirm_invalid_json");
+          emitProxyTerminalFromStatus(correlation, 400, { reason: "invalid_json" });
           sendJson(res, 400, {
             error: "Bad request",
-            message: "Invalid JSON body for /mnemospark-cloud upload/confirm"
+            message: "Invalid JSON body for /mnemospark_cloud upload/confirm"
           });
           return;
         }
         const requestPayload = parseStorageUploadConfirmRequest(payload);
         if (!requestPayload) {
           logProxyEvent("warn", "proxy_upload_confirm_missing_fields");
+          emitProxyTerminalFromStatus(correlation, 400, { reason: "missing_fields" });
           sendJson(res, 400, {
             error: "Bad request",
             message: "Missing required fields: quote_id, wallet_address, object_key, idempotency_key"
           });
           return;
         }
+        correlation.quote_id = requestPayload.quote_id;
+        correlation.wallet_address = requestPayload.wallet_address;
+        correlation.object_key = requestPayload.object_key;
         if (requestPayload.wallet_address.toLowerCase() !== proxyWalletAddressLower) {
           logProxyEvent("warn", "proxy_upload_confirm_wallet_mismatch", {
             request_wallet: requestPayload.wallet_address,
             proxy_wallet: account.address
           });
+          emitProxyTerminalFromStatus(correlation, 403, { reason: "wallet_mismatch" });
           sendJson(res, 403, {
             error: "wallet_proof_invalid",
             message: "wallet proof invalid"
@@ -2107,8 +2162,10 @@ async function startProxy(options) {
           logProxyEvent("warn", "proxy_upload_confirm_wallet_signature_missing");
           res.writeHead(400, { "Content-Type": "application/json" });
           res.end(createWalletRequiredBody());
+          emitProxyTerminalFromStatus(correlation, 400, { reason: "wallet_signature_missing" });
           return;
         }
+        emitProxyEvent("storage.call", "start", correlation, { target: "storage/upload/confirm" });
         const backendResponse = await forwardStorageUploadConfirmToBackend(requestPayload, {
           backendBaseUrl: MNEMOSPARK_BACKEND_API_BASE_URL,
           walletSignature
@@ -2116,6 +2173,7 @@ async function startProxy(options) {
         logProxyEvent("info", "proxy_upload_confirm_backend_response", {
           status: backendResponse.status
         });
+        emitProxyEvent("storage.call", "result", correlation, { status: backendResponse.status });
         const authFailure = normalizeBackendAuthFailure(
           backendResponse.status,
           backendResponse.bodyText
@@ -2131,27 +2189,29 @@ async function startProxy(options) {
           });
           res.writeHead(authFailure.status, responseHeaders2);
           res.end(authFailure.bodyText);
+          emitProxyTerminalFromStatus(correlation, authFailure.status, { reason: "auth_failure" });
           return;
         }
         const responseHeaders = createBackendForwardHeaders(backendResponse);
         res.writeHead(backendResponse.status, responseHeaders);
         res.end(backendResponse.bodyText);
+        emitProxyTerminalFromStatus(correlation, backendResponse.status);
       } catch (err) {
+        emitProxyEvent("terminal.failure", "failure", correlation, {
+          error: err instanceof Error ? err.message : String(err)
+        });
         logProxyEvent("error", "proxy_upload_confirm_forward_failed", {
           error: err instanceof Error ? err.message : String(err)
         });
         sendJson(res, 502, {
           error: "proxy_error",
-          message: `Failed to forward /mnemospark-cloud upload/confirm: ${err instanceof Error ? err.message : String(err)}`
+          message: `Failed to forward /mnemospark_cloud upload/confirm: ${err instanceof Error ? err.message : String(err)}`
         });
       }
       return;
     }
     if (req.method === "POST" && matchesProxyPath(req.url, STORAGE_LS_PROXY_PATH)) {
-      const correlation = {
-        trace_id: randomUUID(),
-        operation_id: randomUUID()
-      };
+      const correlation = createProxyCorrelation(req.headers);
       logProxyEvent("info", "proxy_ls_received");
       emitProxyEvent("request.received", "start", correlation, { path: STORAGE_LS_PROXY_PATH });
       try {
@@ -2160,15 +2220,17 @@ async function startProxy(options) {
           payload = await readProxyJsonBody(req);
         } catch {
           logProxyEvent("warn", "proxy_ls_invalid_json");
+          emitProxyTerminalFromStatus(correlation, 400, { reason: "invalid_json" });
           sendJson(res, 400, {
             error: "Bad request",
-            message: "Invalid JSON body for /mnemospark-cloud ls"
+            message: "Invalid JSON body for /mnemospark_cloud ls"
           });
           return;
         }
         const requestPayload = parseStorageObjectRequest(payload);
         if (!requestPayload) {
           logProxyEvent("warn", "proxy_ls_missing_fields");
+          emitProxyTerminalFromStatus(correlation, 400, { reason: "missing_fields" });
           sendJson(res, 400, {
             error: "Bad request",
             message: "Missing required fields: wallet_address, object_key"
@@ -2179,6 +2241,7 @@ async function startProxy(options) {
         correlation.object_key = requestPayload.object_key;
         if (requestPayload.wallet_address.toLowerCase() !== proxyWalletAddressLower) {
           logProxyEvent("warn", "proxy_ls_wallet_mismatch");
+          emitProxyTerminalFromStatus(correlation, 403, { reason: "wallet_mismatch" });
           sendJson(res, 403, {
             error: "wallet_proof_invalid",
             message: "wallet proof invalid"
@@ -2194,6 +2257,7 @@ async function startProxy(options) {
           logProxyEvent("warn", "proxy_ls_wallet_signature_missing");
           res.writeHead(400, { "Content-Type": "application/json" });
           res.end(createWalletRequiredBody());
+          emitProxyTerminalFromStatus(correlation, 400, { reason: "wallet_signature_missing" });
           return;
         }
         emitProxyEvent("storage.call", "start", correlation, { target: "storage/ls" });
@@ -2216,14 +2280,13 @@ async function startProxy(options) {
           });
           res.writeHead(authFailure.status, responseHeaders2);
           res.end(authFailure.bodyText);
+          emitProxyTerminalFromStatus(correlation, authFailure.status, { reason: "auth_failure" });
           return;
         }
         const responseHeaders = createBackendForwardHeaders(backendResponse);
         res.writeHead(backendResponse.status, responseHeaders);
         res.end(backendResponse.bodyText);
-        emitProxyEvent("terminal.success", "success", correlation, {
-          status: backendResponse.status
-        });
+        emitProxyTerminalFromStatus(correlation, backendResponse.status);
       } catch (err) {
         emitProxyEvent("terminal.failure", "failure", correlation, {
           error: err instanceof Error ? err.message : String(err)
@@ -2233,16 +2296,13 @@ async function startProxy(options) {
         });
         sendJson(res, 502, {
           error: "proxy_error",
-          message: `Failed to forward /mnemospark-cloud ls: ${err instanceof Error ? err.message : String(err)}`
+          message: `Failed to forward /mnemospark_cloud ls: ${err instanceof Error ? err.message : String(err)}`
         });
       }
       return;
     }
     if (req.method === "POST" && matchesProxyPath(req.url, STORAGE_DOWNLOAD_PROXY_PATH)) {
-      const correlation = {
-        trace_id: randomUUID(),
-        operation_id: randomUUID()
-      };
+      const correlation = createProxyCorrelation(req.headers);
       logProxyEvent("info", "proxy_download_received");
       emitProxyEvent("request.received", "start", correlation, {
         path: STORAGE_DOWNLOAD_PROXY_PATH
@@ -2253,15 +2313,17 @@ async function startProxy(options) {
           payload = await readProxyJsonBody(req);
         } catch {
           logProxyEvent("warn", "proxy_download_invalid_json");
+          emitProxyTerminalFromStatus(correlation, 400, { reason: "invalid_json" });
           sendJson(res, 400, {
             error: "Bad request",
-            message: "Invalid JSON body for /mnemospark-cloud download"
+            message: "Invalid JSON body for /mnemospark_cloud download"
           });
           return;
         }
         const requestPayload = parseStorageObjectRequest(payload);
         if (!requestPayload) {
           logProxyEvent("warn", "proxy_download_missing_fields");
+          emitProxyTerminalFromStatus(correlation, 400, { reason: "missing_fields" });
           sendJson(res, 400, {
             error: "Bad request",
             message: "Missing required fields: wallet_address, object_key"
@@ -2272,6 +2334,7 @@ async function startProxy(options) {
         correlation.object_key = requestPayload.object_key;
         if (requestPayload.wallet_address.toLowerCase() !== proxyWalletAddressLower) {
           logProxyEvent("warn", "proxy_download_wallet_mismatch");
+          emitProxyTerminalFromStatus(correlation, 403, { reason: "wallet_mismatch" });
           sendJson(res, 403, {
             error: "wallet_proof_invalid",
             message: "wallet proof invalid"
@@ -2287,6 +2350,7 @@ async function startProxy(options) {
           logProxyEvent("warn", "proxy_download_wallet_signature_missing");
           res.writeHead(400, { "Content-Type": "application/json" });
           res.end(createWalletRequiredBody());
+          emitProxyTerminalFromStatus(correlation, 400, { reason: "wallet_signature_missing" });
           return;
         }
         emitProxyEvent("storage.call", "start", correlation, { target: "storage/download" });
@@ -2313,6 +2377,7 @@ async function startProxy(options) {
           });
           res.writeHead(authFailure.status, responseHeaders);
           res.end(authFailure.bodyText);
+          emitProxyTerminalFromStatus(correlation, authFailure.status, { reason: "auth_failure" });
           return;
         }
         if (backendResponse.status < 200 || backendResponse.status >= 300) {
@@ -2322,6 +2387,7 @@ async function startProxy(options) {
           const responseHeaders = createBackendForwardHeaders(backendResponse);
           res.writeHead(backendResponse.status, responseHeaders);
           res.end(backendResponse.bodyText);
+          emitProxyTerminalFromStatus(correlation, backendResponse.status);
           return;
         }
         const downloadResult = await downloadStorageToDisk(requestPayload, backendResponse, {
@@ -2338,9 +2404,7 @@ async function startProxy(options) {
           file_path: downloadResult.filePath,
           bytes_written: downloadResult.bytesWritten
         });
-        emitProxyEvent("terminal.success", "success", correlation, {
-          status: 200
-        });
+        emitProxyTerminalFromStatus(correlation, 200);
       } catch (err) {
         emitProxyEvent("terminal.failure", "failure", correlation, {
           error: err instanceof Error ? err.message : String(err)
@@ -2350,16 +2414,13 @@ async function startProxy(options) {
         });
         sendJson(res, 502, {
           error: "proxy_error",
-          message: `Failed to forward /mnemospark-cloud download: ${err instanceof Error ? err.message : String(err)}`
+          message: `Failed to forward /mnemospark_cloud download: ${err instanceof Error ? err.message : String(err)}`
         });
       }
       return;
     }
     if (req.method === "POST" && matchesProxyPath(req.url, STORAGE_DELETE_PROXY_PATH)) {
-      const correlation = {
-        trace_id: randomUUID(),
-        operation_id: randomUUID()
-      };
+      const correlation = createProxyCorrelation(req.headers);
       logProxyEvent("info", "proxy_delete_received");
       emitProxyEvent("request.received", "start", correlation, { path: STORAGE_DELETE_PROXY_PATH });
       try {
@@ -2368,15 +2429,17 @@ async function startProxy(options) {
           payload = await readProxyJsonBody(req);
         } catch {
           logProxyEvent("warn", "proxy_delete_invalid_json");
+          emitProxyTerminalFromStatus(correlation, 400, { reason: "invalid_json" });
           sendJson(res, 400, {
             error: "Bad request",
-            message: "Invalid JSON body for /mnemospark-cloud delete"
+            message: "Invalid JSON body for /mnemospark_cloud delete"
           });
           return;
         }
         const requestPayload = parseStorageObjectRequest(payload);
         if (!requestPayload) {
           logProxyEvent("warn", "proxy_delete_missing_fields");
+          emitProxyTerminalFromStatus(correlation, 400, { reason: "missing_fields" });
           sendJson(res, 400, {
             error: "Bad request",
             message: "Missing required fields: wallet_address, object_key"
@@ -2387,6 +2450,7 @@ async function startProxy(options) {
         correlation.object_key = requestPayload.object_key;
         if (requestPayload.wallet_address.toLowerCase() !== proxyWalletAddressLower) {
           logProxyEvent("warn", "proxy_delete_wallet_mismatch");
+          emitProxyTerminalFromStatus(correlation, 403, { reason: "wallet_mismatch" });
           sendJson(res, 403, {
             error: "wallet_proof_invalid",
             message: "wallet proof invalid"
@@ -2402,6 +2466,7 @@ async function startProxy(options) {
           logProxyEvent("warn", "proxy_delete_wallet_signature_missing");
           res.writeHead(400, { "Content-Type": "application/json" });
           res.end(createWalletRequiredBody());
+          emitProxyTerminalFromStatus(correlation, 400, { reason: "wallet_signature_missing" });
           return;
         }
         emitProxyEvent("storage.call", "start", correlation, { target: "storage/delete" });
@@ -2428,14 +2493,13 @@ async function startProxy(options) {
           });
           res.writeHead(authFailure.status, responseHeaders2);
           res.end(authFailure.bodyText);
+          emitProxyTerminalFromStatus(correlation, authFailure.status, { reason: "auth_failure" });
           return;
         }
         const responseHeaders = createBackendForwardHeaders(backendResponse);
         res.writeHead(backendResponse.status, responseHeaders);
         res.end(backendResponse.bodyText);
-        emitProxyEvent("terminal.success", "success", correlation, {
-          status: backendResponse.status
-        });
+        emitProxyTerminalFromStatus(correlation, backendResponse.status);
       } catch (err) {
         emitProxyEvent("terminal.failure", "failure", correlation, {
           error: err instanceof Error ? err.message : String(err)
@@ -2445,7 +2509,7 @@ async function startProxy(options) {
         });
         sendJson(res, 502, {
           error: "proxy_error",
-          message: `Failed to forward /mnemospark-cloud delete: ${err instanceof Error ? err.message : String(err)}`
+          message: `Failed to forward /mnemospark_cloud delete: ${err instanceof Error ? err.message : String(err)}`
         });
       }
       return;
@@ -2691,7 +2755,7 @@ import { mkdir as mkdir4 } from "fs/promises";
 import { homedir as homedir5 } from "os";
 import { dirname as dirname4, join as join7 } from "path";
 var DB_SUBPATH = join7(".openclaw", "mnemospark", "state.db");
-var SCHEMA_VERSION = 2;
+var SCHEMA_VERSION = 3;
 function resolveDbPath(homeDir) {
   return join7(homeDir ?? homedir5(), DB_SUBPATH);
 }
@@ -2797,6 +2861,21 @@ async function createCloudDatastore(homeDir) {
       CREATE INDEX IF NOT EXISTS idx_friendly_names_wallet ON friendly_names(wallet_address);
       CREATE INDEX IF NOT EXISTS idx_friendly_names_created_at ON friendly_names(created_at);
     `);
+    const addOperationsColumn = (columnName, sqlType) => {
+      try {
+        nextDb.exec(`ALTER TABLE operations ADD COLUMN ${columnName} ${sqlType}`);
+      } catch (error) {
+        const message = error instanceof Error ? error.message.toLowerCase() : String(error);
+        if (!message.includes("duplicate column name")) {
+          throw error;
+        }
+      }
+    };
+    addOperationsColumn("trace_id", "TEXT");
+    addOperationsColumn("orchestrator", "TEXT");
+    addOperationsColumn("subagent_session_id", "TEXT");
+    addOperationsColumn("timeout_seconds", "INTEGER");
+    addOperationsColumn("cancel_requested_at", "TEXT");
     nextDb.prepare(
       `INSERT INTO schema_migrations(version, applied_at)
        VALUES(?, ?)
@@ -2808,7 +2887,10 @@ async function createCloudDatastore(homeDir) {
     try {
       await ensureReady();
       return fn();
-    } catch {
+    } catch (error) {
+      if (process.env.MNEMOSPARK_SQLITE_STRICT === "1") {
+        throw error;
+      }
       return fallback;
     }
   };
@@ -2933,13 +3015,19 @@ async function createCloudDatastore(homeDir) {
     upsertOperation: async (row) => {
       await safe(() => {
         const ts = nowIso();
+        const terminalStatuses = /* @__PURE__ */ new Set(["succeeded", "failed", "cancelled", "timed_out"]);
         db.prepare(
-          `INSERT INTO operations(operation_id, type, object_id, quote_id, status, error_code, error_message, started_at, finished_at, created_at, updated_at)
-           VALUES(?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+          `INSERT INTO operations(operation_id, type, object_id, quote_id, trace_id, orchestrator, subagent_session_id, timeout_seconds, cancel_requested_at, status, error_code, error_message, started_at, finished_at, created_at, updated_at)
+           VALUES(?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
            ON CONFLICT(operation_id) DO UPDATE SET
              type=excluded.type,
-             object_id=excluded.object_id,
-             quote_id=excluded.quote_id,
+             object_id=COALESCE(excluded.object_id, operations.object_id),
+             quote_id=COALESCE(excluded.quote_id, operations.quote_id),
+             trace_id=COALESCE(excluded.trace_id, operations.trace_id),
+             orchestrator=COALESCE(excluded.orchestrator, operations.orchestrator),
+             subagent_session_id=COALESCE(excluded.subagent_session_id, operations.subagent_session_id),
+             timeout_seconds=COALESCE(excluded.timeout_seconds, operations.timeout_seconds),
+             cancel_requested_at=COALESCE(excluded.cancel_requested_at, operations.cancel_requested_at),
              status=excluded.status,
              error_code=excluded.error_code,
              error_message=excluded.error_message,
@@ -2951,11 +3039,16 @@ async function createCloudDatastore(homeDir) {
           row.type,
           row.object_id,
           row.quote_id,
+          row.trace_id ?? null,
+          row.orchestrator ?? null,
+          row.subagent_session_id ?? null,
+          row.timeout_seconds ?? null,
+          row.cancel_requested_at ?? null,
           row.status,
           row.error_code,
           row.error_message,
           row.status === "started" ? ts : null,
-          row.status === "succeeded" || row.status === "failed" ? ts : null,
+          terminalStatuses.has(row.status) ? ts : null,
           ts,
           ts
         );
@@ -2963,7 +3056,7 @@ async function createCloudDatastore(homeDir) {
     },
     findOperationById: async (operationId) => safe(() => {
       const row = db.prepare(
-        `SELECT operation_id, type, status, error_code, error_message, started_at, finished_at, updated_at
+        `SELECT operation_id, type, object_id, quote_id, trace_id, orchestrator, subagent_session_id, timeout_seconds, cancel_requested_at, status, error_code, error_message, started_at, finished_at, updated_at
              FROM operations
              WHERE operation_id = ?
              LIMIT 1`
@@ -3065,7 +3158,9 @@ var REQUIRED_UPLOAD = "--quote-id, --wallet-address, --object-id, --object-id-ha
 var REQUIRED_STORAGE_OBJECT = "--wallet-address and one of (--object-key | --name [--latest|--at])";
 var BOOLEAN_SELECTOR_FLAGS = /* @__PURE__ */ new Set(["latest"]);
 var BOOLEAN_ASYNC_FLAGS = /* @__PURE__ */ new Set(["async"]);
+var BOOLEAN_OP_STATUS_FLAGS = /* @__PURE__ */ new Set(["cancel"]);
 var BOOLEAN_SELECTOR_AND_ASYNC_FLAGS = /* @__PURE__ */ new Set(["latest", "async"]);
+var ORCHESTRATOR_MODES = /* @__PURE__ */ new Set(["inline", "subagent"]);
 function expandTilde(path) {
   const trimmed = path.trim();
   if (trimmed === "~") {
@@ -3079,29 +3174,54 @@ function expandTilde(path) {
 var CLOUD_HELP_TEXT = [
   "\u2601\uFE0F **mnemospark Cloud Commands**",
   "",
-  "\u2022 `/mnemospark-cloud` or `/mnemospark-cloud help` \u2014 show this message",
+  "\u2022 `/mnemospark_cloud` or `/mnemospark_cloud help` \u2014 show this message",
   "",
-  "\u2022 `/mnemospark-cloud backup <file>` or `/mnemospark-cloud backup <directory> [--name <friendly-name>]`",
-  "  Required: <file> or <directory> (path to back up)",
+  "\u2022 `/mnemospark_cloud backup <file|directory> [--name <friendly-name>] [--async] [--orchestrator <inline|subagent>] [--timeout-seconds <n>]`",
+  "  Purpose: create a local tar+gzip backup object and index it for later upload.",
+  "  Required: <file|directory>",
   "",
-  "\u2022 `/mnemospark-cloud price-storage --wallet-address <addr> --object-id <id> --object-id-hash <hash> --gb <gb> --provider <provider> --region <region>`",
+  "\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.",
   "  Required: " + REQUIRED_PRICE_STORAGE,
   "",
-  "\u2022 `/mnemospark-cloud upload --quote-id <quote-id> --wallet-address <addr> --object-id <id> --object-id-hash <hash> [--name <friendly-name>] [--async]`",
+  "\u2022 `/mnemospark_cloud upload --quote-id <quote-id> --wallet-address <addr> --object-id <id> --object-id-hash <hash> [--name <friendly-name>] [--async] [--orchestrator <inline|subagent>] [--timeout-seconds <n>]`",
+  "  Purpose: upload an encrypted object using a valid quote-id.",
   "  Required: " + REQUIRED_UPLOAD,
   "",
-  "\u2022 `/mnemospark-cloud ls --wallet-address <addr> [--object-key <object-key> | --name <friendly-name>] [--latest|--at <timestamp>]`",
+  "\u2022 `/mnemospark_cloud ls --wallet-address <addr> [--object-key <object-key> | --name <friendly-name>] [--latest|--at <timestamp>]`",
+  "  Purpose: look up remote object metadata.",
   "  Required: " + REQUIRED_STORAGE_OBJECT,
   "",
-  "\u2022 `/mnemospark-cloud download --wallet-address <addr> [--object-key <object-key> | --name <friendly-name>] [--latest|--at <timestamp>] [--async]`",
+  "\u2022 `/mnemospark_cloud download --wallet-address <addr> [--object-key <object-key> | --name <friendly-name>] [--latest|--at <timestamp>] [--async] [--orchestrator <inline|subagent>] [--timeout-seconds <n>]`",
+  "  Purpose: fetch an object to local disk.",
   "  Required: " + REQUIRED_STORAGE_OBJECT,
   "",
-  "\u2022 `/mnemospark-cloud delete --wallet-address <addr> [--object-key <object-key> | --name <friendly-name>] [--latest|--at <timestamp>]`",
+  "\u2022 `/mnemospark_cloud delete --wallet-address <addr> [--object-key <object-key> | --name <friendly-name>] [--latest|--at <timestamp>]`",
+  "  Purpose: remove a remote object and local cron tracking when present.",
   "  Required: " + REQUIRED_STORAGE_OBJECT,
   "",
-  "\u2022 `/mnemospark-cloud op-status --operation-id <id>`",
+  "\u2022 `/mnemospark_cloud op-status --operation-id <id> [--cancel]`",
+  "  Purpose: inspect async operation status, or request cancellation for subagent runs.",
   "  Required: --operation-id",
   "",
+  "Async orchestration flags (`backup`, `upload`, `download` only):",
+  "\u2022 `--async`",
+  "  Start operation in background and return quickly with operation-id.",
+  "\u2022 `--orchestrator <inline|subagent>`",
+  "  Choose async engine. Default when omitted is `inline`.",
+  "  Use `subagent` for explicit subagent session tracking and cancellation.",
+  "\u2022 `--timeout-seconds <n>`",
+  "  Optional per-operation timeout. Valid only with `--async --orchestrator subagent`.",
+  "  `n` must be a positive integer (seconds).",
+  "\u2022 `op-status --cancel`",
+  "  Cancel a subagent-orchestrated operation by operation-id (idempotent).",
+  "",
+  "Examples:",
+  "\u2022 `/mnemospark_cloud upload ... --async --orchestrator subagent`",
+  "\u2022 `/mnemospark_cloud download ... --async --orchestrator subagent --timeout-seconds 900`",
+  "\u2022 `/mnemospark_cloud op-status --operation-id <id>`",
+  "\u2022 `/mnemospark_cloud op-status --operation-id <id> --cancel`",
+  "",
   "Backup creates a tar+gzip object in ~/.openclaw/mnemospark/backup and appends object metadata to ~/.openclaw/mnemospark/object.log. Upload appends storage rows and cron-tracking rows to object.log, and keeps job entries in ~/.openclaw/mnemospark/crontab.txt. All storage commands (price-storage, upload, ls, download, delete) require --wallet-address."
 ].join("\n");
 var UnsupportedBackupPlatformError = class extends Error {
@@ -3191,9 +3311,73 @@ function parseStorageObjectRequestInput(flags, selector) {
     location
   });
 }
-function stripAsyncFlag(args) {
+function parseOrchestratorMode(value) {
+  if (!value) {
+    return void 0;
+  }
+  const normalized = value.trim().toLowerCase();
+  if (!normalized) {
+    return null;
+  }
+  if (!ORCHESTRATOR_MODES.has(normalized)) {
+    return null;
+  }
+  return normalized;
+}
+function parseTimeoutSeconds(value) {
+  if (!value) {
+    return void 0;
+  }
+  const trimmed = value.trim();
+  if (!/^\d+$/.test(trimmed)) {
+    return null;
+  }
+  const parsed = Number.parseInt(trimmed, 10);
+  if (!Number.isFinite(parsed) || parsed <= 0) {
+    return null;
+  }
+  return parsed;
+}
+function parseAsyncOperationArgs(flags) {
+  const asyncRequested = flags.async === "true";
+  const hasOrchestratorFlag = typeof flags.orchestrator === "string";
+  const hasTimeoutFlag = typeof flags["timeout-seconds"] === "string";
+  if (!asyncRequested && (hasOrchestratorFlag || hasTimeoutFlag)) {
+    return null;
+  }
+  const parsedOrchestrator = parseOrchestratorMode(flags.orchestrator);
+  if (parsedOrchestrator === null) {
+    return null;
+  }
+  const parsedTimeoutSeconds = parseTimeoutSeconds(flags["timeout-seconds"]);
+  if (parsedTimeoutSeconds === null) {
+    return null;
+  }
+  if (typeof parsedTimeoutSeconds === "number" && (parsedOrchestrator ?? "inline") !== "subagent") {
+    return null;
+  }
+  return {
+    async: asyncRequested,
+    orchestrator: parsedOrchestrator === void 0 ? void 0 : parsedOrchestrator,
+    timeoutSeconds: parsedTimeoutSeconds === void 0 ? void 0 : parsedTimeoutSeconds
+  };
+}
+var INVALID_ASYNC_FLAGS_MESSAGE = "invalid async flags. `--orchestrator`/`--timeout-seconds` require `--async`, and `--timeout-seconds` is only valid with `--orchestrator subagent`.";
+function stripAsyncControlFlags(args) {
   const tokens = tokenizeArgsRaw(args ?? "");
-  const filtered = tokens.filter((token) => token.toLowerCase() !== "--async");
+  const filtered = [];
+  for (let idx = 0; idx < tokens.length; idx += 1) {
+    const token = tokens[idx];
+    const lowerToken = token.toLowerCase();
+    if (lowerToken === "--async") {
+      continue;
+    }
+    if (lowerToken === "--orchestrator" || lowerToken === "--timeout-seconds") {
+      idx += 1;
+      continue;
+    }
+    filtered.push(token);
+  }
   return filtered.join(" ");
 }
 function parseCloudArgs(args) {
@@ -3216,8 +3400,21 @@ function parseCloudArgs(args) {
     if (!backupTarget) {
       return { mode: "unknown" };
     }
-    const flags = parseNamedFlagsTokens(tokens.slice(1));
-    return { mode: "backup", backupTarget, friendlyName: flags?.name?.trim() || void 0 };
+    const remainingTokens = tokens.slice(1);
+    const flags = remainingTokens.length === 0 ? {} : parseNamedFlagsTokens(remainingTokens, BOOLEAN_ASYNC_FLAGS);
+    if (!flags) {
+      return { mode: "backup-invalid" };
+    }
+    const asyncArgs = parseAsyncOperationArgs(flags);
+    if (!asyncArgs) {
+      return { mode: "backup-invalid-async" };
+    }
+    return {
+      mode: "backup",
+      backupTarget,
+      friendlyName: flags.name?.trim() || void 0,
+      ...asyncArgs
+    };
   }
   if (subcommand === "price-storage") {
     const flags = parseNamedFlags(rest);
@@ -3243,6 +3440,10 @@ function parseCloudArgs(args) {
     if (!flags) {
       return { mode: "upload-invalid" };
     }
+    const asyncArgs = parseAsyncOperationArgs(flags);
+    if (!asyncArgs) {
+      return { mode: "upload-invalid-async" };
+    }
     const quoteId = flags["quote-id"]?.trim();
     const walletAddress = flags["wallet-address"]?.trim();
     const objectId = flags["object-id"]?.trim();
@@ -3253,7 +3454,7 @@ function parseCloudArgs(args) {
     return {
       mode: "upload",
       friendlyName: flags.name?.trim() || void 0,
-      async: flags.async === "true",
+      ...asyncArgs,
       uploadRequest: {
         quote_id: quoteId,
         wallet_address: walletAddress,
@@ -3282,6 +3483,10 @@ function parseCloudArgs(args) {
     if (!flags) {
       return { mode: "download-invalid" };
     }
+    const asyncArgs = parseAsyncOperationArgs(flags);
+    if (!asyncArgs) {
+      return { mode: "download-invalid-async" };
+    }
     const selector = parseObjectSelector(flags);
     if (!selector) {
       return { mode: "download-invalid" };
@@ -3294,7 +3499,7 @@ function parseCloudArgs(args) {
       mode: "download",
       storageObjectRequest: request,
       nameSelector: selector.nameSelector,
-      async: flags.async === "true"
+      ...asyncArgs
     };
   }
   if (subcommand === "delete") {
@@ -3313,12 +3518,12 @@ function parseCloudArgs(args) {
     return { mode: "delete", storageObjectRequest: request, nameSelector: selector.nameSelector };
   }
   if (subcommand === "op-status") {
-    const flags = parseNamedFlags(rest);
+    const flags = parseNamedFlags(rest, BOOLEAN_OP_STATUS_FLAGS);
     const operationId = flags?.["operation-id"]?.trim();
     if (!operationId) {
       return { mode: "op-status-invalid" };
     }
-    return { mode: "op-status", operationId };
+    return { mode: "op-status", operationId, cancel: flags?.cancel === "true" };
   }
   return { mode: "unknown" };
 }
@@ -3809,17 +4014,37 @@ async function uploadPresignedObjectIfNeeded(uploadResponse, uploadMode, encrypt
   if (!headers.has("content-type")) {
     headers.set("content-type", "application/octet-stream");
   }
-  const response = await fetchImpl(uploadResponse.upload_url, {
+  const putBody = new Uint8Array(encryptedContent);
+  const firstAttempt = await fetchImpl(uploadResponse.upload_url, {
     method: "PUT",
     headers,
-    body: new Uint8Array(encryptedContent)
+    body: putBody,
+    redirect: "manual"
   });
-  if (!response.ok) {
-    const details = (await response.text()).trim();
-    throw new Error(
-      `Presigned upload failed with status ${response.status}${details ? `: ${details}` : ""}`
-    );
+  if (firstAttempt.ok) {
+    return;
+  }
+  if ((firstAttempt.status === 307 || firstAttempt.status === 308) && firstAttempt.headers.has("location")) {
+    const location = firstAttempt.headers.get("location")?.trim();
+    if (location) {
+      const redirectedAttempt = await fetchImpl(location, {
+        method: "PUT",
+        headers,
+        body: putBody
+      });
+      if (redirectedAttempt.ok) {
+        return;
+      }
+      const redirectedDetails = (await redirectedAttempt.text()).trim();
+      throw new Error(
+        `Presigned upload failed after redirect with status ${redirectedAttempt.status}${redirectedDetails ? `: ${redirectedDetails}` : ""}`
+      );
+    }
   }
+  const details = (await firstAttempt.text()).trim();
+  throw new Error(
+    `Presigned upload failed with status ${firstAttempt.status}${details ? `: ${details}` : ""}`
+  );
 }
 async function appendStorageUploadLog(upload, homeDir, nowDateFn = () => /* @__PURE__ */ new Date()) {
   return appendObjectLogLine(
@@ -3890,16 +4115,118 @@ function extractUploadErrorMessage(error) {
 function formatPriceStorageUserMessage(quote) {
   return [
     `Your storage quote \`${quote.quote_id}\` is valid for 1 hour, the storage price is \`${quote.storage_price}\` for \`${quote.object_id}\` with file size of \`${quote.object_size_gb}\` in \`${quote.provider}\` \`${quote.location}\``,
-    `If you accept this quote run the command /mnemospark-cloud upload --quote-id \`${quote.quote_id}\` --wallet-address \`${quote.addr}\` --object-id \`${quote.object_id}\` --object-id-hash \`${quote.object_id_hash}\``
+    `If you accept this quote run the command /mnemospark_cloud upload --quote-id \`${quote.quote_id}\` --wallet-address \`${quote.addr}\` --object-id \`${quote.object_id}\` --object-id-hash \`${quote.object_id_hash}\``
   ].join("\n");
 }
 function formatStorageLsUserMessage(result, requestedObjectKey) {
   const objectId = result.object_id ?? result.key;
   return `${objectId} with ${requestedObjectKey} is ${result.size_bytes} in ${result.bucket}`;
 }
+function createInProcessSubagentOrchestrator() {
+  const sessions = /* @__PURE__ */ new Map();
+  const completeSession = async (sessionId, handler) => {
+    const session = sessions.get(sessionId);
+    if (!session || session.terminal) {
+      return false;
+    }
+    session.terminal = true;
+    if (session.timeoutHandle) {
+      clearTimeout(session.timeoutHandle);
+    }
+    sessions.delete(sessionId);
+    await handler(session.hooks);
+    return true;
+  };
+  return {
+    dispatch: async (input) => {
+      const sessionId = `agent:mnemospark:subagent:${randomUUID3()}`;
+      const state = {
+        terminal: false,
+        cancelRequested: false,
+        hooks: input.hooks
+      };
+      sessions.set(sessionId, state);
+      if (typeof input.timeoutSeconds === "number" && input.timeoutSeconds > 0) {
+        state.timeoutHandle = setTimeout(() => {
+          void completeSession(sessionId, async (hooks) => {
+            await hooks?.onTimedOut?.(sessionId);
+          });
+        }, input.timeoutSeconds * 1e3);
+      }
+      setTimeout(() => {
+        void (async () => {
+          try {
+            await input.hooks?.onRunning?.(sessionId);
+            await input.hooks?.onProgress?.(sessionId, "subagent execution started");
+            const result = await input.runTask();
+            const session = sessions.get(sessionId);
+            if (!session || session.terminal) {
+              return;
+            }
+            if (session.cancelRequested) {
+              await completeSession(sessionId, async (hooks) => {
+                await hooks?.onCancelled?.(sessionId, "cancel requested");
+              });
+              return;
+            }
+            if (result.isError) {
+              await completeSession(sessionId, async (hooks) => {
+                await hooks?.onFailed?.(sessionId, {
+                  code: "ASYNC_FAILED",
+                  message: result.text
+                });
+              });
+              return;
+            }
+            await completeSession(sessionId, async (hooks) => {
+              await hooks?.onCompleted?.(sessionId, result);
+            });
+          } catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            const session = sessions.get(sessionId);
+            if (!session || session.terminal) {
+              return;
+            }
+            if (session.cancelRequested) {
+              await completeSession(sessionId, async (hooks) => {
+                await hooks?.onCancelled?.(sessionId, "cancel requested");
+              });
+              return;
+            }
+            await completeSession(sessionId, async (hooks) => {
+              await hooks?.onFailed?.(sessionId, {
+                code: "ASYNC_EXCEPTION",
+                message
+              });
+            });
+          }
+        })();
+      }, 0);
+      return { sessionId };
+    },
+    cancel: async (sessionId, reason) => {
+      const session = sessions.get(sessionId);
+      if (!session) {
+        return { accepted: false };
+      }
+      if (session.terminal) {
+        return { accepted: false, alreadyTerminal: true };
+      }
+      session.cancelRequested = true;
+      await completeSession(sessionId, async (hooks) => {
+        await hooks?.onCancelled?.(sessionId, reason ?? "cancel requested");
+      });
+      return { accepted: true };
+    }
+  };
+}
 function createCloudCommand(options = {}) {
+  const subagentOrchestrator = options.subagentOrchestrator ?? createInProcessSubagentOrchestrator();
   return {
-    name: "mnemospark-cloud",
+    name: "mnemospark_cloud",
+    nativeNames: {
+      default: "mnemospark_cloud"
+    },
     description: "Manage mnemospark cloud storage workflow commands",
     acceptsArgs: true,
     requireAuth: true,
@@ -3923,6 +4250,7 @@ function createCloudCommand(options = {}) {
           proxyQuoteOptions: options.proxyQuoteOptions,
           proxyUploadOptions: options.proxyUploadOptions,
           proxyUploadConfirmOptions: options.proxyUploadConfirmOptions,
+          subagentOrchestrator,
           proxyStorageOptions: options.proxyStorageOptions
         });
       } catch (outerError) {
@@ -3932,7 +4260,42 @@ function createCloudCommand(options = {}) {
     }
   };
 }
-async function resolveNameSelectorIfNeeded(datastore, request, selector) {
+async function resolveFriendlyNameFromManifest(params, homeDir) {
+  const manifestPath = join8(homeDir ?? homedir6(), ".openclaw", "mnemospark", "manifest.jsonl");
+  let manifestRaw;
+  try {
+    manifestRaw = await readFile3(manifestPath, "utf-8");
+  } catch {
+    return { objectKey: null, matchCount: 0 };
+  }
+  const wallet = params.walletAddress.trim();
+  const name = params.friendlyName.trim();
+  const atMs = params.at ? Date.parse(params.at) : Number.NaN;
+  const hasAt = Number.isFinite(atMs);
+  const rows = manifestRaw.split(/\r?\n/).map((line) => line.trim()).filter(Boolean).map((line) => {
+    try {
+      return JSON.parse(line);
+    } catch {
+      return null;
+    }
+  }).filter((row) => Boolean(row)).filter((row) => {
+    if (!row.object_key || !row.friendly_name || !row.wallet_address || !row.created_at)
+      return false;
+    if (row.friendly_name !== name) return false;
+    if (row.wallet_address.trim() !== wallet) return false;
+    if (params.latest || !hasAt) return true;
+    const createdAtMs = Date.parse(row.created_at);
+    return Number.isFinite(createdAtMs) && createdAtMs <= atMs;
+  }).sort((a, b) => Date.parse(b.created_at ?? "") - Date.parse(a.created_at ?? ""));
+  if (rows.length === 0) {
+    return { objectKey: null, matchCount: 0 };
+  }
+  if (!params.latest && !hasAt && rows.length > 1) {
+    return { objectKey: null, matchCount: rows.length };
+  }
+  return { objectKey: rows[0].object_key ?? null, matchCount: rows.length };
+}
+async function resolveNameSelectorIfNeeded(datastore, request, selector, homeDir) {
   if (!selector) {
     const parsedRequest2 = parseStorageObjectRequest(request);
     if (!parsedRequest2) {
@@ -3940,6 +4303,12 @@ async function resolveNameSelectorIfNeeded(datastore, request, selector) {
     }
     return { request: parsedRequest2 };
   }
+  let sqliteUnavailable = false;
+  try {
+    await datastore.ensureReady();
+  } catch {
+    sqliteUnavailable = true;
+  }
   const matches = await datastore.countFriendlyNameMatches(request.wallet_address, selector.name);
   if (matches > 1 && !selector.latest && !selector.at) {
     return {
@@ -3952,18 +4321,41 @@ async function resolveNameSelectorIfNeeded(datastore, request, selector) {
     latest: selector.latest,
     at: selector.at
   });
-  if (!resolved || !resolved.objectKey) {
+  let resolvedObjectKey = resolved?.objectKey ?? null;
+  let degradedWarning;
+  if (!resolvedObjectKey && sqliteUnavailable) {
+    const manifestResolved = await resolveFriendlyNameFromManifest(
+      {
+        walletAddress: request.wallet_address,
+        friendlyName: selector.name,
+        latest: selector.latest,
+        at: selector.at
+      },
+      homeDir
+    );
+    if (manifestResolved.matchCount > 1 && !selector.latest && !selector.at) {
+      return {
+        error: `Multiple objects match --name ${selector.name}. Add --latest or --at <timestamp>.`
+      };
+    }
+    resolvedObjectKey = manifestResolved.objectKey;
+    if (resolvedObjectKey) {
+      degradedWarning = "SQLite friendly-name index unavailable; resolved --name via manifest.jsonl fallback.";
+    }
+  }
+  if (!resolvedObjectKey) {
     return { error: `No object found for --name ${selector.name}.` };
   }
   const parsedRequest = parseStorageObjectRequest({
     ...request,
-    object_key: resolved.objectKey
+    object_key: resolvedObjectKey
   });
   if (!parsedRequest) {
     return { error: "Cannot resolve storage object request." };
   }
   return {
-    request: parsedRequest
+    request: parsedRequest,
+    degradedWarning
   };
 }
 async function emitCloudEvent(eventType, details, homeDir) {
@@ -3983,7 +4375,44 @@ async function emitCloudEventBestEffort(eventType, details, homeDir) {
   } catch {
   }
 }
-async function runCloudCommandHandler(ctx, options) {
+function toOperationEventPayload(eventType, context) {
+  return {
+    operation_id: context.operationId,
+    trace_id: context.traceId,
+    event_type: eventType,
+    status: context.status,
+    ts: (/* @__PURE__ */ new Date()).toISOString(),
+    wallet_address: context.walletAddress ?? void 0,
+    object_id: context.objectId ?? void 0,
+    object_key: context.objectKey ?? void 0,
+    quote_id: context.quoteId ?? void 0,
+    orchestrator: context.orchestrator ?? void 0,
+    "subagent-session-id": context.subagentSessionId ?? void 0,
+    "timeout-seconds": context.timeoutSeconds ?? void 0,
+    "error-code": context.errorCode ?? void 0,
+    "error-message": context.errorMessage ?? void 0,
+    progress: context.progressMessage ?? void 0
+  };
+}
+async function emitOperationEvent(eventType, context, homeDir) {
+  const payload = toOperationEventPayload(eventType, context);
+  await Promise.all([
+    appendJsonlEvent("events.jsonl", payload, homeDir),
+    appendJsonlEvent("proxy-events.jsonl", payload, homeDir)
+  ]);
+}
+async function emitOperationEventBestEffort(eventType, context, homeDir) {
+  try {
+    await emitOperationEvent(eventType, context, homeDir);
+  } catch {
+  }
+}
+function buildRequestCorrelation(forcedOperationId, forcedTraceId) {
+  const operationId = forcedOperationId?.trim() || randomUUID3();
+  const traceId = forcedTraceId?.trim() || randomUUID3();
+  return { operationId, traceId };
+}
+async function runCloudCommandHandler(ctx, options, executionContext = {}) {
   const parsed = parseCloudArgs(ctx.args);
   const objectLogHomeDir = options.objectLogHomeDir;
   const backupBuilder = options.buildBackupObjectFn;
@@ -3998,6 +4427,7 @@ async function runCloudCommandHandler(ctx, options) {
   const requestStorageLs = options.requestStorageLsFn;
   const requestStorageDownload = options.requestStorageDownloadFn;
   const requestStorageDelete = options.requestStorageDeleteFn;
+  const subagentOrchestrator = options.subagentOrchestrator;
   if (parsed.mode === "help" || parsed.mode === "unknown") {
     return {
       text: CLOUD_HELP_TEXT,
@@ -4010,12 +4440,30 @@ async function runCloudCommandHandler(ctx, options) {
       isError: true
     };
   }
+  if (parsed.mode === "backup-invalid") {
+    return {
+      text: "Cannot build storage object",
+      isError: true
+    };
+  }
+  if (parsed.mode === "backup-invalid-async") {
+    return {
+      text: `Cannot build storage object: ${INVALID_ASYNC_FLAGS_MESSAGE}`,
+      isError: true
+    };
+  }
   if (parsed.mode === "upload-invalid") {
     return {
       text: `Cannot upload storage object: required arguments are ${REQUIRED_UPLOAD}.`,
       isError: true
     };
   }
+  if (parsed.mode === "upload-invalid-async") {
+    return {
+      text: `Cannot upload storage object: ${INVALID_ASYNC_FLAGS_MESSAGE}`,
+      isError: true
+    };
+  }
   if (parsed.mode === "ls-invalid") {
     return {
       text: `Cannot list storage object: required arguments are ${REQUIRED_STORAGE_OBJECT}.`,
@@ -4028,6 +4476,12 @@ async function runCloudCommandHandler(ctx, options) {
       isError: true
     };
   }
+  if (parsed.mode === "download-invalid-async") {
+    return {
+      text: `Cannot download file: ${INVALID_ASYNC_FLAGS_MESSAGE}`,
+      isError: true
+    };
+  }
   if (parsed.mode === "delete-invalid") {
     return {
       text: `Cannot delete file: required arguments are ${REQUIRED_STORAGE_OBJECT}.`,
@@ -4041,66 +4495,450 @@ async function runCloudCommandHandler(ctx, options) {
     };
   }
   const datastore = await createCloudDatastore(objectLogHomeDir);
+  const terminalOperationStatuses = /* @__PURE__ */ new Set(["succeeded", "failed", "cancelled", "timed_out"]);
+  const isTerminalOperationStatus = (status) => terminalOperationStatuses.has(status);
+  const formatOperationStatus = (operation) => ({
+    text: [
+      `operation-id: ${operation.operation_id}`,
+      `type: ${operation.type}`,
+      `status: ${operation.status}`,
+      `started-at: ${operation.started_at ?? "n/a"}`,
+      `finished-at: ${operation.finished_at ?? "n/a"}`,
+      operation.orchestrator ? `orchestrator: ${operation.orchestrator}` : null,
+      operation.subagent_session_id ? `subagent-session-id: ${operation.subagent_session_id}` : null,
+      operation.timeout_seconds ? `timeout-seconds: ${operation.timeout_seconds}` : null,
+      operation.error_code ? `error-code: ${operation.error_code}` : null,
+      operation.error_message ? `error-message: ${operation.error_message}` : null
+    ].filter((v) => Boolean(v)).join("\n"),
+    isError: operation.status === "failed" || operation.status === "cancelled" || operation.status === "timed_out"
+  });
   if (parsed.mode === "op-status") {
-    const operation = await datastore.findOperationById(parsed.operationId);
+    let operation = await datastore.findOperationById(parsed.operationId);
     if (!operation) {
       return {
         text: `Operation not found: ${parsed.operationId}`,
         isError: true
       };
     }
-    return {
-      text: [
-        `operation-id: ${operation.operation_id}`,
-        `type: ${operation.type}`,
-        `status: ${operation.status}`,
-        `started-at: ${operation.started_at ?? "n/a"}`,
-        `finished-at: ${operation.finished_at ?? "n/a"}`,
-        operation.error_code ? `error-code: ${operation.error_code}` : null,
-        operation.error_message ? `error-message: ${operation.error_message}` : null
-      ].filter((v) => Boolean(v)).join("\n"),
-      isError: operation.status === "failed"
-    };
+    if (parsed.cancel) {
+      if (operation.orchestrator !== "subagent" || !operation.subagent_session_id) {
+        return {
+          text: "Cancellation is only supported for subagent-orchestrated operations.",
+          isError: true
+        };
+      }
+      if (!isTerminalOperationStatus(operation.status)) {
+        const traceId = operation.trace_id ?? randomUUID3();
+        const cancelRequestedAt = (/* @__PURE__ */ new Date()).toISOString();
+        await datastore.upsertOperation({
+          operation_id: operation.operation_id,
+          type: operation.type,
+          object_id: operation.object_id,
+          quote_id: operation.quote_id,
+          trace_id: traceId,
+          orchestrator: "subagent",
+          subagent_session_id: operation.subagent_session_id,
+          timeout_seconds: operation.timeout_seconds,
+          cancel_requested_at: cancelRequestedAt,
+          status: "running",
+          error_code: null,
+          error_message: null
+        });
+        await emitOperationEventBestEffort(
+          "operation.cancel.requested",
+          {
+            operationId: operation.operation_id,
+            traceId,
+            status: "running",
+            objectId: operation.object_id,
+            quoteId: operation.quote_id,
+            orchestrator: "subagent",
+            subagentSessionId: operation.subagent_session_id,
+            timeoutSeconds: operation.timeout_seconds
+          },
+          objectLogHomeDir
+        );
+        const cancelResult = await subagentOrchestrator.cancel(
+          operation.subagent_session_id,
+          "cancel requested by op-status"
+        );
+        if (cancelResult.accepted || cancelResult.alreadyTerminal) {
+          const afterCancel = await datastore.findOperationById(parsed.operationId);
+          if (afterCancel && !isTerminalOperationStatus(afterCancel.status)) {
+            await datastore.upsertOperation({
+              operation_id: operation.operation_id,
+              type: operation.type,
+              object_id: operation.object_id,
+              quote_id: operation.quote_id,
+              trace_id: traceId,
+              orchestrator: "subagent",
+              subagent_session_id: operation.subagent_session_id,
+              timeout_seconds: operation.timeout_seconds,
+              cancel_requested_at: cancelRequestedAt,
+              status: "cancelled",
+              error_code: "ASYNC_CANCELLED",
+              error_message: "Operation cancelled by user request."
+            });
+            await emitOperationEventBestEffort(
+              "operation.cancelled",
+              {
+                operationId: operation.operation_id,
+                traceId,
+                status: "cancelled",
+                objectId: operation.object_id,
+                quoteId: operation.quote_id,
+                orchestrator: "subagent",
+                subagentSessionId: operation.subagent_session_id,
+                timeoutSeconds: operation.timeout_seconds,
+                errorCode: "ASYNC_CANCELLED",
+                errorMessage: "Operation cancelled by user request."
+              },
+              objectLogHomeDir
+            );
+          }
+        }
+      }
+      operation = await datastore.findOperationById(parsed.operationId);
+      if (!operation) {
+        return {
+          text: `Operation not found: ${parsed.operationId}`,
+          isError: true
+        };
+      }
+    }
+    return formatOperationStatus(operation);
   }
-  if ((parsed.mode === "upload" || parsed.mode === "download") && parsed.async) {
-    const operationId = randomUUID3();
+  if ((parsed.mode === "backup" || parsed.mode === "upload" || parsed.mode === "download") && parsed.async) {
+    const asyncCorrelation = buildRequestCorrelation();
+    const operationId = asyncCorrelation.operationId;
     const opType = parsed.mode;
-    const opObject = parsed.mode === "upload" ? parsed.uploadRequest.object_id : parsed.storageObjectRequest.object_key ?? null;
+    const opObject = parsed.mode === "upload" ? parsed.uploadRequest.object_id : null;
     const opQuote = parsed.mode === "upload" ? parsed.uploadRequest.quote_id : null;
+    const orchestratorMode = parsed.orchestrator ?? "inline";
+    const timeoutSeconds = orchestratorMode === "subagent" ? parsed.timeoutSeconds ?? null : null;
+    const eventContextBase = {
+      operationId,
+      traceId: asyncCorrelation.traceId,
+      walletAddress: parsed.mode === "upload" ? parsed.uploadRequest.wallet_address : parsed.mode === "download" ? parsed.storageObjectRequest.wallet_address : null,
+      objectId: opObject,
+      objectKey: parsed.mode === "download" ? parsed.storageObjectRequest.object_key ?? null : null,
+      quoteId: opQuote,
+      orchestrator: orchestratorMode,
+      timeoutSeconds
+    };
     await datastore.upsertOperation({
       operation_id: operationId,
       type: opType,
       object_id: opObject,
       quote_id: opQuote,
+      trace_id: asyncCorrelation.traceId,
+      orchestrator: orchestratorMode,
+      timeout_seconds: timeoutSeconds,
       status: "started",
       error_code: null,
       error_message: null
     });
-    const syncArgs = stripAsyncFlag(ctx.args);
-    void runCloudCommandHandler({ args: syncArgs }, options).then(async (result) => {
+    await emitOperationEventBestEffort(
+      "operation.dispatched",
+      { ...eventContextBase, status: "started" },
+      objectLogHomeDir
+    );
+    const syncArgs = stripAsyncControlFlags(ctx.args);
+    if (orchestratorMode === "subagent") {
+      const subagentTask = {
+        schema: "mnemospark.subagent-task.v1",
+        operationId,
+        traceId: asyncCorrelation.traceId,
+        command: parsed.mode,
+        args: syncArgs,
+        timeoutSeconds: parsed.timeoutSeconds,
+        requestedBy: {
+          pluginCommand: "mnemospark_cloud",
+          chatId: ctx.channel,
+          senderId: ctx.senderId
+        }
+      };
+      try {
+        const dispatchResult = await subagentOrchestrator.dispatch({
+          task: subagentTask,
+          timeoutSeconds: parsed.timeoutSeconds,
+          runTask: async () => runCloudCommandHandler(
+            { args: syncArgs, channel: ctx.channel, senderId: ctx.senderId },
+            options,
+            {
+              forcedOperationId: asyncCorrelation.operationId,
+              forcedTraceId: asyncCorrelation.traceId
+            }
+          ),
+          hooks: {
+            onRunning: async (sessionId) => {
+              await datastore.upsertOperation({
+                operation_id: operationId,
+                type: opType,
+                object_id: opObject,
+                quote_id: opQuote,
+                trace_id: asyncCorrelation.traceId,
+                orchestrator: "subagent",
+                subagent_session_id: sessionId,
+                timeout_seconds: timeoutSeconds,
+                status: "running",
+                error_code: null,
+                error_message: null
+              });
+              await emitOperationEventBestEffort(
+                "operation.progress",
+                {
+                  ...eventContextBase,
+                  status: "running",
+                  subagentSessionId: sessionId,
+                  progressMessage: "subagent running"
+                },
+                objectLogHomeDir
+              );
+            },
+            onProgress: async (sessionId, message) => {
+              await emitOperationEventBestEffort(
+                "operation.progress",
+                {
+                  ...eventContextBase,
+                  status: "running",
+                  subagentSessionId: sessionId,
+                  progressMessage: message
+                },
+                objectLogHomeDir
+              );
+            },
+            onCompleted: async (sessionId) => {
+              await datastore.upsertOperation({
+                operation_id: operationId,
+                type: opType,
+                object_id: opObject,
+                quote_id: opQuote,
+                trace_id: asyncCorrelation.traceId,
+                orchestrator: "subagent",
+                subagent_session_id: sessionId,
+                timeout_seconds: timeoutSeconds,
+                status: "succeeded",
+                error_code: null,
+                error_message: null
+              });
+              await emitOperationEventBestEffort(
+                "operation.completed",
+                {
+                  ...eventContextBase,
+                  status: "succeeded",
+                  subagentSessionId: sessionId
+                },
+                objectLogHomeDir
+              );
+            },
+            onFailed: async (sessionId, details) => {
+              await datastore.upsertOperation({
+                operation_id: operationId,
+                type: opType,
+                object_id: opObject,
+                quote_id: opQuote,
+                trace_id: asyncCorrelation.traceId,
+                orchestrator: "subagent",
+                subagent_session_id: sessionId,
+                timeout_seconds: timeoutSeconds,
+                status: "failed",
+                error_code: details.code,
+                error_message: details.message
+              });
+              await emitOperationEventBestEffort(
+                "operation.completed",
+                {
+                  ...eventContextBase,
+                  status: "failed",
+                  subagentSessionId: sessionId,
+                  errorCode: details.code,
+                  errorMessage: details.message
+                },
+                objectLogHomeDir
+              );
+            },
+            onCancelled: async (sessionId, reason) => {
+              await datastore.upsertOperation({
+                operation_id: operationId,
+                type: opType,
+                object_id: opObject,
+                quote_id: opQuote,
+                trace_id: asyncCorrelation.traceId,
+                orchestrator: "subagent",
+                subagent_session_id: sessionId,
+                timeout_seconds: timeoutSeconds,
+                cancel_requested_at: (/* @__PURE__ */ new Date()).toISOString(),
+                status: "cancelled",
+                error_code: "ASYNC_CANCELLED",
+                error_message: reason ?? "Operation cancelled."
+              });
+              await emitOperationEventBestEffort(
+                "operation.cancelled",
+                {
+                  ...eventContextBase,
+                  status: "cancelled",
+                  subagentSessionId: sessionId,
+                  errorCode: "ASYNC_CANCELLED",
+                  errorMessage: reason ?? "Operation cancelled."
+                },
+                objectLogHomeDir
+              );
+            },
+            onTimedOut: async (sessionId) => {
+              await datastore.upsertOperation({
+                operation_id: operationId,
+                type: opType,
+                object_id: opObject,
+                quote_id: opQuote,
+                trace_id: asyncCorrelation.traceId,
+                orchestrator: "subagent",
+                subagent_session_id: sessionId,
+                timeout_seconds: timeoutSeconds,
+                status: "timed_out",
+                error_code: "ASYNC_TIMEOUT",
+                error_message: "Operation timed out."
+              });
+              await emitOperationEventBestEffort(
+                "operation.timed_out",
+                {
+                  ...eventContextBase,
+                  status: "timed_out",
+                  subagentSessionId: sessionId,
+                  errorCode: "ASYNC_TIMEOUT",
+                  errorMessage: "Operation timed out."
+                },
+                objectLogHomeDir
+              );
+            }
+          }
+        });
+        const operationAfterDispatch = await datastore.findOperationById(operationId);
+        if (operationAfterDispatch?.subagent_session_id !== dispatchResult.sessionId) {
+          await datastore.upsertOperation({
+            operation_id: operationId,
+            type: opType,
+            object_id: opObject,
+            quote_id: opQuote,
+            trace_id: asyncCorrelation.traceId,
+            orchestrator: "subagent",
+            subagent_session_id: dispatchResult.sessionId,
+            timeout_seconds: timeoutSeconds,
+            status: operationAfterDispatch?.status ?? "started",
+            error_code: operationAfterDispatch?.error_code ?? null,
+            error_message: operationAfterDispatch?.error_message ?? null
+          });
+        }
+        return {
+          text: [
+            `Operation started in background. operation-id: ${operationId}`,
+            `orchestrator: subagent`,
+            `subagent-session-id: ${dispatchResult.sessionId}`,
+            timeoutSeconds ? `timeout-seconds: ${timeoutSeconds}` : null,
+            `Use /mnemospark_cloud op-status --operation-id ${operationId}`
+          ].filter((line) => Boolean(line)).join("\n")
+        };
+      } catch (dispatchError) {
+        const dispatchMessage = dispatchError instanceof Error ? dispatchError.message : String(dispatchError);
+        await datastore.upsertOperation({
+          operation_id: operationId,
+          type: opType,
+          object_id: opObject,
+          quote_id: opQuote,
+          trace_id: asyncCorrelation.traceId,
+          orchestrator: "subagent",
+          timeout_seconds: timeoutSeconds,
+          status: "failed",
+          error_code: "ASYNC_DISPATCH_FAILED",
+          error_message: dispatchMessage
+        });
+        await emitOperationEventBestEffort(
+          "operation.completed",
+          {
+            ...eventContextBase,
+            status: "failed",
+            errorCode: "ASYNC_DISPATCH_FAILED",
+            errorMessage: dispatchMessage
+          },
+          objectLogHomeDir
+        );
+        return {
+          text: `Cannot dispatch subagent operation: ${dispatchMessage}
+operation-id: ${operationId}`,
+          isError: true
+        };
+      }
+    }
+    await datastore.upsertOperation({
+      operation_id: operationId,
+      type: opType,
+      object_id: opObject,
+      quote_id: opQuote,
+      trace_id: asyncCorrelation.traceId,
+      orchestrator: "inline",
+      status: "running",
+      error_code: null,
+      error_message: null
+    });
+    void runCloudCommandHandler(
+      { args: syncArgs, channel: ctx.channel, senderId: ctx.senderId },
+      options,
+      {
+        forcedOperationId: asyncCorrelation.operationId,
+        forcedTraceId: asyncCorrelation.traceId
+      }
+    ).then(async (result) => {
       await datastore.upsertOperation({
         operation_id: operationId,
         type: opType,
         object_id: opObject,
         quote_id: opQuote,
+        trace_id: asyncCorrelation.traceId,
+        orchestrator: "inline",
         status: result.isError ? "failed" : "succeeded",
         error_code: result.isError ? "ASYNC_FAILED" : null,
         error_message: result.isError ? result.text : null
       });
+      await emitOperationEventBestEffort(
+        "operation.completed",
+        {
+          ...eventContextBase,
+          status: result.isError ? "failed" : "succeeded",
+          errorCode: result.isError ? "ASYNC_FAILED" : null,
+          errorMessage: result.isError ? result.text : null
+        },
+        objectLogHomeDir
+      );
     }).catch(async (err) => {
+      const errorMessage = err instanceof Error ? err.message : String(err);
       await datastore.upsertOperation({
         operation_id: operationId,
         type: opType,
         object_id: opObject,
         quote_id: opQuote,
+        trace_id: asyncCorrelation.traceId,
+        orchestrator: "inline",
         status: "failed",
         error_code: "ASYNC_EXCEPTION",
-        error_message: err instanceof Error ? err.message : String(err)
+        error_message: errorMessage
       });
+      await emitOperationEventBestEffort(
+        "operation.completed",
+        {
+          ...eventContextBase,
+          status: "failed",
+          errorCode: "ASYNC_EXCEPTION",
+          errorMessage
+        },
+        objectLogHomeDir
+      );
     });
     return {
-      text: `Operation started in background. operation-id: ${operationId}
-Use /mnemospark-cloud op-status --operation-id ${operationId}`
+      text: [
+        `Operation started in background. operation-id: ${operationId}`,
+        `orchestrator: inline`,
+        `Use /mnemospark_cloud op-status --operation-id ${operationId}`
+      ].join("\n")
     };
   }
   if (parsed.mode === "backup") {
@@ -4158,11 +4996,12 @@ Use /mnemospark-cloud op-status --operation-id ${operationId}`
     }
   }
   if (parsed.mode === "price-storage") {
+    const correlation = buildRequestCorrelation();
     try {
-      const quote = await requestPriceStorageQuote(
-        parsed.priceStorageRequest,
-        options.proxyQuoteOptions
-      );
+      const quote = await requestPriceStorageQuote(parsed.priceStorageRequest, {
+        ...options.proxyQuoteOptions,
+        correlation
+      });
       await appendPriceStorageQuoteLog(quote, objectLogHomeDir);
       await datastore.upsertObject({
         object_id: quote.object_id,
@@ -4183,10 +5022,33 @@ Use /mnemospark-cloud op-status --operation-id ${operationId}`
         network: null,
         status: "quoted"
       });
+      await emitCloudEventBestEffort(
+        "price-storage.completed",
+        {
+          operation_id: correlation.operationId,
+          trace_id: correlation.traceId,
+          wallet_address: quote.addr,
+          object_id: quote.object_id,
+          quote_id: quote.quote_id,
+          status: "succeeded"
+        },
+        objectLogHomeDir
+      );
       return {
         text: formatPriceStorageUserMessage(quote)
       };
     } catch (err) {
+      await emitCloudEventBestEffort(
+        "price-storage.completed",
+        {
+          operation_id: correlation.operationId,
+          trace_id: correlation.traceId,
+          wallet_address: parsed.priceStorageRequest.wallet_address,
+          object_id: parsed.priceStorageRequest.object_id,
+          status: "failed"
+        },
+        objectLogHomeDir
+      );
       const message = err instanceof Error ? err.message : typeof err === "string" ? err : String(err);
       return {
         text: message ? `Cannot price storage: ${message}` : "Cannot price storage",
@@ -4195,11 +5057,15 @@ Use /mnemospark-cloud op-status --operation-id ${operationId}`
     }
   }
   if (parsed.mode === "upload") {
+    const uploadCorrelation = buildRequestCorrelation(
+      executionContext.forcedOperationId ?? idempotencyKeyFn(),
+      executionContext.forcedTraceId
+    );
     try {
       const loggedQuote = await datastore.findQuoteById(parsed.uploadRequest.quote_id) ?? await findLoggedPriceStorageQuote(parsed.uploadRequest.quote_id, objectLogHomeDir);
       if (!loggedQuote) {
         return {
-          text: "Cannot upload storage object: quote-id not found in object.log. Run /mnemospark-cloud price-storage first.",
+          text: "Cannot upload storage object: quote-id not found in object.log. Run /mnemospark_cloud price-storage first.",
           isError: true
         };
       }
@@ -4218,7 +5084,7 @@ Use /mnemospark-cloud op-status --operation-id ${operationId}`
         archiveStats = await stat2(archivePath);
       } catch {
         return {
-          text: `Cannot upload storage object: local archive not found at ${archivePath}. Run /mnemospark-cloud backup first.`,
+          text: `Cannot upload storage object: local archive not found at ${archivePath}. Run /mnemospark_cloud backup first.`,
           isError: true
         };
       }
@@ -4248,7 +5114,7 @@ Use /mnemospark-cloud op-status --operation-id ${operationId}`
         parsed.uploadRequest.wallet_address,
         objectLogHomeDir
       );
-      const idempotencyKey = idempotencyKeyFn();
+      const idempotencyKey = uploadCorrelation.operationId;
       const shouldSettleBeforeUpload = requestStorageUpload !== requestStorageUploadViaProxy;
       if (shouldSettleBeforeUpload) {
         const paymentFetch = createPayment(walletKey).fetch;
@@ -4257,6 +5123,7 @@ Use /mnemospark-cloud op-status --operation-id ${operationId}`
           parsed.uploadRequest.wallet_address,
           {
             ...options.proxyUploadOptions,
+            correlation: uploadCorrelation,
             fetchImpl: (input, init) => paymentFetch(input, init)
           }
         );
@@ -4278,6 +5145,7 @@ Use /mnemospark-cloud op-status --operation-id ${operationId}`
         {
           ...options.proxyUploadOptions,
           idempotencyKey,
+          correlation: uploadCorrelation,
           fetchImpl: uploadFetchImpl
         }
       );
@@ -4297,7 +5165,10 @@ Use /mnemospark-cloud op-status --operation-id ${operationId}`
               object_key: uploadResponse.object_key,
               idempotency_key: idempotencyKey
             },
-            options.proxyUploadConfirmOptions
+            {
+              ...options.proxyUploadConfirmOptions,
+              correlation: uploadCorrelation
+            }
           );
         } catch (confirmError) {
           const transId = uploadResponse.trans_id ?? "unknown";
@@ -4346,18 +5217,50 @@ Use /mnemospark-cloud op-status --operation-id ${operationId}`
         status: "active"
       });
       if (parsed.friendlyName?.trim()) {
+        const normalizedFriendlyName = parsed.friendlyName.trim();
         await datastore.upsertFriendlyName({
-          friendly_name: parsed.friendlyName.trim(),
+          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
+          });
+          friendlyNameVerified = Boolean(readBack?.objectKey) && readBack?.objectKey === finalizedUploadResponse.object_key;
+        } catch {
+          friendlyNameVerified = false;
+        }
+        if (!friendlyNameVerified) {
+          const warning = "SQLite friendly-name write verification failed; manifest fallback may be required for --name lookups.";
+          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
+            },
+            objectLogHomeDir
+          );
+          if (process.env.MNEMOSPARK_SQLITE_STRICT === "1") {
+            throw new Error(warning);
+          }
+        }
         try {
           await appendJsonlEvent(
             "manifest.jsonl",
             {
-              friendly_name: parsed.friendlyName.trim(),
+              friendly_name: normalizedFriendlyName,
               object_id: finalizedUploadResponse.object_id,
               object_key: finalizedUploadResponse.object_key,
               quote_id: finalizedUploadResponse.quote_id,
@@ -4373,6 +5276,7 @@ Use /mnemospark-cloud op-status --operation-id ${operationId}`
         "upload.completed",
         {
           operation_id: idempotencyKey,
+          trace_id: uploadCorrelation.traceId,
           wallet_address: finalizedUploadResponse.addr,
           object_id: finalizedUploadResponse.object_id,
           object_key: finalizedUploadResponse.object_key,
@@ -4386,6 +5290,18 @@ Use /mnemospark-cloud op-status --operation-id ${operationId}`
         text: formatStorageUploadUserMessage(finalizedUploadResponse, cronJob.cronId)
       };
     } catch (error) {
+      await emitCloudEventBestEffort(
+        "upload.completed",
+        {
+          operation_id: uploadCorrelation.operationId,
+          trace_id: uploadCorrelation.traceId,
+          wallet_address: parsed.uploadRequest.wallet_address,
+          object_id: parsed.uploadRequest.object_id,
+          quote_id: parsed.uploadRequest.quote_id,
+          status: "failed"
+        },
+        objectLogHomeDir
+      );
       const uploadErrorMessage = extractUploadErrorMessage(error);
       return {
         text: uploadErrorMessage ?? "Cannot upload storage object",
@@ -4397,31 +5313,49 @@ Use /mnemospark-cloud op-status --operation-id ${operationId}`
     const resolved = await resolveNameSelectorIfNeeded(
       datastore,
       parsed.storageObjectRequest,
-      parsed.nameSelector
+      parsed.nameSelector,
+      objectLogHomeDir
     );
     if (resolved.error || !resolved.request) {
       return { text: resolved.error ?? "Cannot resolve storage object request.", isError: true };
     }
     const resolvedRequest = resolved.request;
-    const operationId = randomUUID3();
+    if (resolved.degradedWarning) {
+      await emitCloudEventBestEffort(
+        "name_resolution.degraded",
+        {
+          wallet_address: resolvedRequest.wallet_address,
+          object_key: resolvedRequest.object_key,
+          warning: resolved.degradedWarning
+        },
+        objectLogHomeDir
+      );
+    }
+    const correlation = buildRequestCorrelation();
+    const operationId = correlation.operationId;
+    const knownObject = await datastore.findObjectByObjectKey(resolvedRequest.object_key);
+    const operationObjectId = knownObject?.object_id ?? null;
     await datastore.upsertOperation({
       operation_id: operationId,
       type: "ls",
-      object_id: resolvedRequest.object_key,
+      object_id: operationObjectId,
       quote_id: null,
       status: "started",
       error_code: null,
       error_message: null
     });
     try {
-      const lsResult = await requestStorageLs(resolvedRequest, options.proxyStorageOptions);
+      const lsResult = await requestStorageLs(resolvedRequest, {
+        ...options.proxyStorageOptions,
+        correlation
+      });
       if (!lsResult.success) {
         throw new Error("ls failed");
       }
       await datastore.upsertOperation({
         operation_id: operationId,
         type: "ls",
-        object_id: resolvedRequest.object_key,
+        object_id: operationObjectId,
         quote_id: null,
         status: "succeeded",
         error_code: null,
@@ -4431,20 +5365,23 @@ Use /mnemospark-cloud op-status --operation-id ${operationId}`
         "ls.completed",
         {
           operation_id: operationId,
+          trace_id: correlation.traceId,
           wallet_address: resolvedRequest.wallet_address,
           object_key: resolvedRequest.object_key,
           status: "succeeded"
         },
         objectLogHomeDir
       );
+      const lsText = formatStorageLsUserMessage(lsResult, resolvedRequest.object_key);
       return {
-        text: formatStorageLsUserMessage(lsResult, resolvedRequest.object_key)
+        text: resolved.degradedWarning ? `${resolved.degradedWarning}
+${lsText}` : lsText
       };
     } catch {
       await datastore.upsertOperation({
         operation_id: operationId,
         type: "ls",
-        object_id: resolvedRequest.object_key,
+        object_id: operationObjectId,
         quote_id: null,
         status: "failed",
         error_code: "LS_FAILED",
@@ -4454,6 +5391,7 @@ Use /mnemospark-cloud op-status --operation-id ${operationId}`
         "ls.completed",
         {
           operation_id: operationId,
+          trace_id: correlation.traceId,
           wallet_address: resolvedRequest.wallet_address,
           object_key: resolvedRequest.object_key,
           status: "failed"
@@ -4470,34 +5408,52 @@ Use /mnemospark-cloud op-status --operation-id ${operationId}`
     const resolved = await resolveNameSelectorIfNeeded(
       datastore,
       parsed.storageObjectRequest,
-      parsed.nameSelector
+      parsed.nameSelector,
+      objectLogHomeDir
     );
     if (resolved.error || !resolved.request) {
       return { text: resolved.error ?? "Cannot resolve storage object request.", isError: true };
     }
     const resolvedRequest = resolved.request;
-    const operationId = randomUUID3();
+    if (resolved.degradedWarning) {
+      await emitCloudEventBestEffort(
+        "name_resolution.degraded",
+        {
+          wallet_address: resolvedRequest.wallet_address,
+          object_key: resolvedRequest.object_key,
+          warning: resolved.degradedWarning
+        },
+        objectLogHomeDir
+      );
+    }
+    const correlation = buildRequestCorrelation(
+      executionContext.forcedOperationId,
+      executionContext.forcedTraceId
+    );
+    const operationId = correlation.operationId;
+    const knownObject = await datastore.findObjectByObjectKey(resolvedRequest.object_key);
+    const operationObjectId = knownObject?.object_id ?? null;
     await datastore.upsertOperation({
       operation_id: operationId,
       type: "download",
-      object_id: resolvedRequest.object_key,
+      object_id: operationObjectId,
       quote_id: null,
       status: "started",
       error_code: null,
       error_message: null
     });
     try {
-      const downloadResult = await requestStorageDownload(
-        resolvedRequest,
-        options.proxyStorageOptions
-      );
+      const downloadResult = await requestStorageDownload(resolvedRequest, {
+        ...options.proxyStorageOptions,
+        correlation
+      });
       if (!downloadResult.success) {
         throw new Error("download failed");
       }
       await datastore.upsertOperation({
         operation_id: operationId,
         type: "download",
-        object_id: resolvedRequest.object_key,
+        object_id: operationObjectId,
         quote_id: null,
         status: "succeeded",
         error_code: null,
@@ -4507,20 +5463,23 @@ Use /mnemospark-cloud op-status --operation-id ${operationId}`
         "download.completed",
         {
           operation_id: operationId,
+          trace_id: correlation.traceId,
           wallet_address: resolvedRequest.wallet_address,
           object_key: resolvedRequest.object_key,
           status: "succeeded"
         },
         objectLogHomeDir
       );
+      const downloadText = `File ${resolvedRequest.object_key} downloaded to ${downloadResult.file_path}`;
       return {
-        text: `File ${resolvedRequest.object_key} downloaded to ${downloadResult.file_path}`
+        text: resolved.degradedWarning ? `${resolved.degradedWarning}
+${downloadText}` : downloadText
       };
     } catch {
       await datastore.upsertOperation({
         operation_id: operationId,
         type: "download",
-        object_id: resolvedRequest.object_key,
+        object_id: operationObjectId,
         quote_id: null,
         status: "failed",
         error_code: "DOWNLOAD_FAILED",
@@ -4530,6 +5489,7 @@ Use /mnemospark-cloud op-status --operation-id ${operationId}`
         "download.completed",
         {
           operation_id: operationId,
+          trace_id: correlation.traceId,
           wallet_address: resolvedRequest.wallet_address,
           object_key: resolvedRequest.object_key,
           status: "failed"
@@ -4546,16 +5506,32 @@ Use /mnemospark-cloud op-status --operation-id ${operationId}`
     const resolved = await resolveNameSelectorIfNeeded(
       datastore,
       parsed.storageObjectRequest,
-      parsed.nameSelector
+      parsed.nameSelector,
+      objectLogHomeDir
     );
     if (resolved.error || !resolved.request) {
       return { text: resolved.error ?? "Cannot resolve storage object request.", isError: true };
     }
     const resolvedRequest = resolved.request;
-    const operationId = randomUUID3();
+    if (resolved.degradedWarning) {
+      await emitCloudEventBestEffort(
+        "name_resolution.degraded",
+        {
+          wallet_address: resolvedRequest.wallet_address,
+          object_key: resolvedRequest.object_key,
+          warning: resolved.degradedWarning
+        },
+        objectLogHomeDir
+      );
+    }
+    const correlation = buildRequestCorrelation();
+    const operationId = correlation.operationId;
     const existingObjectByKey = await datastore.findObjectByObjectKey(resolvedRequest.object_key);
     try {
-      const deleteResult = await requestStorageDelete(resolvedRequest, options.proxyStorageOptions);
+      const deleteResult = await requestStorageDelete(resolvedRequest, {
+        ...options.proxyStorageOptions,
+        correlation
+      });
       if (!deleteResult.success) {
         throw new Error("delete failed");
       }
@@ -4564,6 +5540,7 @@ Use /mnemospark-cloud op-status --operation-id ${operationId}`
         "delete.completed",
         {
           operation_id: operationId,
+          trace_id: correlation.traceId,
           wallet_address: resolvedRequest.wallet_address,
           object_key: resolvedRequest.object_key,
           status: "failed"
@@ -4621,18 +5598,21 @@ Use /mnemospark-cloud op-status --operation-id ${operationId}`
       "delete.completed",
       {
         operation_id: operationId,
+        trace_id: correlation.traceId,
         wallet_address: resolvedRequest.wallet_address,
         object_key: resolvedRequest.object_key,
         status: "succeeded"
       },
       objectLogHomeDir
     );
+    const deleteText = formatStorageDeleteUserMessage(
+      resolvedRequest.object_key,
+      cronEntry?.cronId ?? null,
+      cronDeleted
+    );
     return {
-      text: formatStorageDeleteUserMessage(
-        resolvedRequest.object_key,
-        cronEntry?.cronId ?? null,
-        cronDeleted
-      )
+      text: resolved.degradedWarning ? `${resolved.degradedWarning}
+${deleteText}` : deleteText
     };
   }
   return {