@membox-cloud/membox 0.1.4 → 0.1.6

package/README.md

@@ -146,6 +146,21 @@ The plugin's `serverUrl` is environment-driven in local development. Source `scr
 
 For local verification, all plugin debug logs can be redirected into the repository `./logs/` directory by exporting `MEMBOX_LOG_FILE` before starting OpenClaw.
 
+For end-to-end diagnostics across plugin + API:
+
+```bash
+export MEMBOX_LOG_FILE="$PWD/logs/plugin-debug.log"
+export MEMBOX_SERVER_LOG_FILE="$PWD/logs/api-debug.log"
+```
+
+When a repro is complete, collect a safe debug bundle with:
+
+```bash
+bash scripts/collect-membox-debug.sh
+```
+
+The bundle includes safe state snapshots, plugin/API logs, and OpenClaw command output. It intentionally excludes raw refresh tokens, device private keys, and vault secret bundles.
+
 For a full manual validation flow, see `./MANUAL-DUAL-DEVICE-CHECKLIST.md`.
 
 For an agent-first install + pairing flow, see `./AGENT-WORKFLOW.md` and run `bash scripts/install-membox-agent-stack.sh` from the repository root.

package/dist/src/api/client.d.ts

@@ -1,7 +1,9 @@
 export declare class ApiError extends Error {
     status: number;
     code: string;
-    constructor(status: number, code: string, message: string);
+    requestId?: string | null | undefined;
+    bodySnippet?: string | null | undefined;
+    constructor(status: number, code: string, message: string, requestId?: string | null | undefined, bodySnippet?: string | null | undefined);
 }
 /**
  * Typed HTTP client for the Membox API.

package/dist/src/api/client.js

@@ -1,14 +1,29 @@
+import { randomUUID } from "node:crypto";
 import { debugLog } from "../debug-logger.js";
 export class ApiError extends Error {
     status;
     code;
-    constructor(status, code, message) {
+    requestId;
+    bodySnippet;
+    constructor(status, code, message, requestId, bodySnippet) {
         super(message);
         this.status = status;
         this.code = code;
+        this.requestId = requestId;
+        this.bodySnippet = bodySnippet;
         this.name = "ApiError";
     }
 }
+function parseErrorBody(bodyText) {
+    if (!bodyText)
+        return null;
+    try {
+        return JSON.parse(bodyText);
+    }
+    catch {
+        return null;
+    }
+}
 /**
  * Typed HTTP client for the Membox API.
  * Handles auth headers and automatic token refresh on 401.
@@ -26,14 +41,16 @@ export class MemboxApiClient {
     }
     async request(method, path, body, retry = true) {
         const url = `${this.baseUrl}${path}`;
+        const requestId = randomUUID();
         const headers = {
             "Content-Type": "application/json",
+            "X-Request-Id": requestId,
         };
         const token = await this.getAccessToken();
         if (token) {
             headers["Authorization"] = `Bearer ${token}`;
         }
-        debugLog.apiRequest(method, url);
+        debugLog.apiRequestWithId(method, url, requestId);
         const t0 = Date.now();
         let res;
         try {
@@ -47,7 +64,8 @@ export class MemboxApiClient {
             debugLog.apiError(method, url, err);
             throw err;
         }
-        debugLog.apiResponse(method, url, res.status, Date.now() - t0);
+        const responseRequestId = res.headers.get("x-request-id") ?? requestId;
+        debugLog.apiResponse(method, url, res.status, Date.now() - t0, responseRequestId);
         if (res.status === 401 && retry) {
             debugLog.info("api-client", "Got 401, attempting token refresh...");
             const refreshed = await this.tryRefresh();
@@ -56,9 +74,15 @@ export class MemboxApiClient {
             }
         }
         if (!res.ok) {
-            const err = (await res.json().catch(() => null));
-            const apiErr = new ApiError(res.status, err?.error?.code ?? "unknown", err?.error?.message ?? res.statusText);
-            debugLog.apiError(method, url, apiErr);
+            const bodyText = await res.text().catch(() => "");
+            const err = parseErrorBody(bodyText);
+            const apiRequestId = err?.error?.request_id ?? responseRequestId;
+            const message = err?.error?.message ?? (bodyText || res.statusText);
+            const apiErr = new ApiError(res.status, err?.error?.code ?? "unknown", message, apiRequestId, bodyText || null);
+            debugLog.apiError(method, url, apiErr, {
+                requestId: apiRequestId,
+                bodySnippet: bodyText || null,
+            });
             throw apiErr;
         }
         // Handle 204 No Content
@@ -74,15 +98,19 @@ export class MemboxApiClient {
             return false;
         }
         const url = `${this.baseUrl}/auth/token/refresh`;
+        const requestId = randomUUID();
         try {
-            debugLog.apiRequest("POST", url);
+            debugLog.apiRequestWithId("POST", url, requestId);
             const t0 = Date.now();
             const res = await fetch(url, {
                 method: "POST",
-                headers: { "Content-Type": "application/json" },
+                headers: {
+                    "Content-Type": "application/json",
+                    "X-Request-Id": requestId,
+                },
                 body: JSON.stringify({ refresh_token: rt }),
             });
-            debugLog.apiResponse("POST", url, res.status, Date.now() - t0);
+            debugLog.apiResponse("POST", url, res.status, Date.now() - t0, res.headers.get("x-request-id") ?? requestId);
             if (!res.ok)
                 return false;
             const data = (await res.json());

package/dist/src/api/device-flow.js

@@ -1,8 +1,16 @@
+import { debugLog } from "../debug-logger.js";
+function shortCode(value) {
+    return value.length <= 16 ? value : `${value.slice(0, 12)}...`;
+}
 export async function startDeviceFlow(client, params) {
-    return client.post("/device/start", params);
+    const result = await client.post("/device/start", params);
+    debugLog.state("setup", `device-start user_code=${result.user_code} device_code=${shortCode(result.device_code)} expires_in=${result.expires_in}s`);
+    return result;
 }
 export async function pollDeviceFlowOnce(client, deviceCode) {
-    return client.get(`/device/poll/${deviceCode}`);
+    const result = await client.get(`/device/poll/${deviceCode}`);
+    debugLog.state("setup", `device-poll device_code=${shortCode(deviceCode)} status=${result.status}`);
+    return result;
 }
 /**
  * Poll the device code endpoint until authorization is granted, denied, or expired.
@@ -22,6 +30,7 @@ export async function pollDeviceFlow(client, deviceCode, interval, expiresIn) {
         }
         catch (err) {
             transientErrors++;
+            debugLog.warn("setup", `device-poll-error device_code=${shortCode(deviceCode)} consecutive_errors=${transientErrors} error=${err instanceof Error ? err.message : String(err)}`);
             if (transientErrors >= MAX_TRANSIENT_ERRORS) {
                 throw new Error(`Device code polling failed after ${MAX_TRANSIENT_ERRORS} consecutive errors: ${err instanceof Error ? err.message : String(err)}`);
             }
@@ -30,6 +39,7 @@ export async function pollDeviceFlow(client, deviceCode, interval, expiresIn) {
         }
         switch (res.status) {
             case "access_granted":
+                debugLog.info("setup", `device-poll-complete device_code=${shortCode(deviceCode)} access_granted`);
                 return {
                     access_token: res.access_token,
                     refresh_token: res.refresh_token,
@@ -38,16 +48,21 @@ export async function pollDeviceFlow(client, deviceCode, interval, expiresIn) {
                     device_id: res.device_id,
                 };
             case "slow_down":
+                debugLog.info("setup", `device-poll-slow-down device_code=${shortCode(deviceCode)} next_wait_ms=${Math.min(waitMs + 1000, 10000)}`);
                 waitMs = Math.min(waitMs + 1000, 10000);
                 break;
             case "expired_token":
+                debugLog.warn("setup", `device-poll-expired device_code=${shortCode(deviceCode)}`);
                 throw new Error("Device code expired. Please try again.");
             case "denied":
+                debugLog.warn("setup", `device-poll-denied device_code=${shortCode(deviceCode)}`);
                 throw new Error("Device authorization was denied.");
             case "authorization_pending":
+                debugLog.info("setup", `device-poll-pending device_code=${shortCode(deviceCode)} wait_ms=${waitMs}`);
                 break;
         }
     }
+    debugLog.error("setup", `device-poll-timeout device_code=${shortCode(deviceCode)}`);
     throw new Error("Device code flow timed out.");
 }
 function sleep(ms) {

package/dist/src/cli/bootstrap.js

@@ -5,6 +5,7 @@ import { generateDeviceKeyPair, } from "../crypto/device-keys.js";
 import { getAccountMe } from "../api/account.js";
 import { MemboxApiClient } from "../api/client.js";
 import { pollDeviceFlow, pollDeviceFlowOnce, startDeviceFlow, } from "../api/device-flow.js";
+import { debugLog } from "../debug-logger.js";
 import { clearPendingSetupSecrets, } from "../store/keychain.js";
 import { clearPendingSetupSecretsFile, getPendingSetupRefreshToken, loadPendingSetupDeviceKeys as loadPendingSetupDeviceKeysFile, storePendingSetupDeviceKeys as storePendingSetupDeviceKeysFile, storePendingSetupRefreshToken, } from "../store/pending-setup-secrets.js";
 import { deletePendingSetup, isPendingSetupExpired, readPendingSetup, writePendingSetup, } from "../store/pending-setup.js";
@@ -78,12 +79,15 @@ export async function clearPendingSetupArtifacts() {
 async function loadActivePendingSetup(cfg) {
     const pendingSetup = await readPendingSetup();
     if (!pendingSetup) {
+        debugLog.state("setup", "pending-setup-none");
         return null;
     }
     if (pendingSetup.server_url !== cfg.serverUrl || isPendingSetupExpired(pendingSetup)) {
+        debugLog.warn("setup", `pending-setup-stale server_url=${pendingSetup.server_url} expected=${cfg.serverUrl} expired=${isPendingSetupExpired(pendingSetup)}`);
         await clearPendingSetupArtifacts();
         return null;
     }
+    debugLog.info("setup", `pending-setup-active status=${pendingSetup.status} user_code=${pendingSetup.user_code}`);
     return pendingSetup;
 }
 async function createPendingSetup(cfg) {
@@ -124,6 +128,7 @@ async function createPendingSetup(cfg) {
     catch (error) {
         throw new Error(`Failed to persist pending setup state on disk: ${error instanceof Error ? error.message : String(error)}`);
     }
+    debugLog.info("setup", `pending-setup-created user_code=${pendingSetup.user_code} device_name=${deviceName} platform=${platform}`);
     return pendingSetup;
 }
 export async function ensurePendingDeviceAuthorization(cfg) {
@@ -203,6 +208,7 @@ export async function pollPendingDeviceAuthorizationOnce(cfg) {
         };
     }
     await clearPendingSetupArtifacts();
+    debugLog.warn("setup", `pending-setup-terminated status=${result.status} device_code=${pendingSetup.device_code.slice(0, 12)}...`);
     return {
         status: result.status === "denied" ? "denied" : "expired",
         pendingSetup: null,
@@ -247,6 +253,7 @@ async function buildAuthorizedContextFromPending(cfg, pendingSetup, options) {
 function printAuthorizationPrompt(pendingSetup) {
     console.log(`\n  Your code: ${pendingSetup.user_code}`);
     console.log(`  Open: ${pendingSetup.verification_uri_complete}\n`);
+    debugLog.info("setup", `authorization-prompt user_code=${pendingSetup.user_code} url=${pendingSetup.verification_uri_complete}`);
 }
 async function waitForPendingAuthorization(cfg, pendingSetup) {
     const client = createAnonymousClient(pendingSetupBaseUrl(cfg));
@@ -257,6 +264,7 @@ async function waitForPendingAuthorization(cfg, pendingSetup) {
     const finalized = await finalizePendingAuthorization(cfg, pendingSetup, tokens);
     console.log("Authorized!");
     console.log(`Logged in as: ${describeAccount(finalized.account)}`);
+    debugLog.info("setup", `authorization-complete user_code=${finalized.pendingSetup.user_code} account=${describeAccount(finalized.account)}`);
     return buildAuthorizedContextFromPending(cfg, finalized.pendingSetup, {
         accessToken: tokens.access_token,
         refreshToken: tokens.refresh_token,
@@ -267,20 +275,25 @@ export async function authorizeDevice(cfg) {
     const { pendingSetup, created } = await ensurePendingDeviceAuthorization(cfg);
     if (pendingSetup.status === "authorized") {
         console.log("Reusing previously completed browser authorization.");
+        debugLog.info("setup", `authorization-reuse user_code=${pendingSetup.user_code} device_id=${pendingSetup.device_id ?? "unknown"}`);
         return buildAuthorizedContextFromPending(cfg, pendingSetup);
     }
     if (created) {
         console.log("Starting device authorization...");
+        debugLog.info("setup", "authorization-start");
     }
     else {
         console.log("Resuming pending device authorization...");
+        debugLog.info("setup", `authorization-resume user_code=${pendingSetup.user_code}`);
     }
     printAuthorizationPrompt(pendingSetup);
     const browserOpened = tryOpenUrl(pendingSetup.verification_uri_complete);
     if (!browserOpened) {
         console.log("  No local browser was opened. If this machine is headless, open that URL in any trusted browser and sign in there.\n");
+        debugLog.warn("setup", "authorization-browser-open-skipped");
     }
     console.log("Waiting for authorization...");
+    debugLog.info("setup", "authorization-waiting");
     return waitForPendingAuthorization(cfg, pendingSetup);
 }
 export async function persistVaultSecrets(params) {

package/dist/src/cli/setup.js

@@ -17,6 +17,7 @@ import { pullAction } from "./pull.js";
 import { authorizeDevice, clearPendingSetupArtifacts, fromB64, persistVaultSecrets, toB64, } from "./bootstrap.js";
 import { runWithProvisioningRollback } from "./provisioning.js";
 import { loadVaultSecretsWithPassphrase } from "../store/vault-secrets.js";
+import { debugLog } from "../debug-logger.js";
 export function selectGrantCapableDevices(devices, currentDeviceId) {
     return devices.filter((device) => device.device_id !== currentDeviceId &&
         device.status === "active" &&
@@ -31,6 +32,7 @@ async function receiveApprovedGrant(params) {
     console.log("Trusted device approval required.");
     console.log("On an existing unlocked device, run `openclaw membox grants approve-pending`.");
     console.log("Waiting for device grant approval...");
+    debugLog.info("setup", `grant-wait-start target_device_id=${params.deviceId}`);
     while (Date.now() < deadline) {
         await new Promise((resolve) => setTimeout(resolve, 2000));
         const grant = await getGrant(params.client, grantRequest.grant_id);
@@ -38,9 +40,11 @@ async function receiveApprovedGrant(params) {
             continue;
         }
         if (grant.status === "rejected") {
+            debugLog.warn("setup", `grant-wait-rejected grant_id=${grantRequest.grant_id}`);
             throw new Error("Trusted-device approval was rejected.");
         }
         if (grant.status === "expired") {
+            debugLog.warn("setup", `grant-wait-expired grant_id=${grantRequest.grant_id}`);
             throw new Error("Trusted-device approval expired before it was approved.");
         }
         if (grant.status !== "approved") {
@@ -70,6 +74,7 @@ export async function finishAuthorizedSetup(cfg, auth, params) {
     const otherGrantCapableDevices = selectGrantCapableDevices(devices, auth.tokens.device_id);
     let amk = null;
     let initialMode = "upload";
+    debugLog.info("setup", `finish-authorized-setup-start device_id=${auth.tokens.device_id} grant_capable_devices=${otherGrantCapableDevices.length} recovery_bundle=${Boolean(recoveryStatus?.has_recovery_bundle)} sync_object_count=${syncStatus?.object_count ?? 0}`);
     try {
         if (otherGrantCapableDevices.length > 0) {
             amk = await receiveApprovedGrant({
@@ -78,6 +83,7 @@ export async function finishAuthorizedSetup(cfg, auth, params) {
                 deviceKeys: auth.deviceKeys,
             });
             initialMode = "pull";
+            debugLog.info("setup", "finish-authorized-setup-mode pull");
         }
         else if (recoveryStatus?.has_recovery_bundle) {
             console.log("Recovery materials already exist for this account, but no active trusted device is available.");
@@ -92,6 +98,7 @@ export async function finishAuthorizedSetup(cfg, auth, params) {
         else {
             console.log("No existing vault detected. Creating a new account master key.");
             amk = generateAMK();
+            debugLog.info("setup", "finish-authorized-setup-mode upload");
         }
         await persistVaultSecrets({
             deviceKeys: auth.deviceKeys,
@@ -117,6 +124,7 @@ export async function finishAuthorizedSetup(cfg, auth, params) {
             });
             await params.onRecoveryCode(recoveryCode);
             recoveryCodeGenerated = true;
+            debugLog.info("setup", "recovery-material-generated");
         }
         const state = createInitialState({
             serverUrl: cfg.serverUrl,
@@ -130,6 +138,7 @@ export async function finishAuthorizedSetup(cfg, auth, params) {
         await writeState(state);
         if (params.enableManagedUnlock) {
             await enableManagedUnlock(params.passphrase);
+            debugLog.info("setup", "managed-unlock-enabled");
         }
         await clearPendingSetupArtifacts();
         const loadedSecrets = await loadVaultSecretsWithPassphrase(params.passphrase);
@@ -148,6 +157,7 @@ export async function finishAuthorizedSetup(cfg, auth, params) {
             const pullResult = await pullAction({ onConflict: "conflict-copy" });
             const downloadedFiles = pullResult.status === "ok" ? pullResult.downloaded : 0;
             console.log("Setup complete! Existing vault material is now available.");
+            debugLog.info("setup", `finish-authorized-setup-complete mode=pull downloaded=${downloadedFiles}`);
             return {
                 initialMode,
                 uploadedFiles: [],
@@ -178,6 +188,7 @@ export async function finishAuthorizedSetup(cfg, auth, params) {
             uploadedFiles.push(path);
         }
         console.log("Setup complete! Vault is ready.");
+        debugLog.info("setup", `finish-authorized-setup-complete mode=upload uploaded=${uploadedFiles.length}`);
         return {
             initialMode,
             uploadedFiles,
@@ -191,30 +202,43 @@ export async function finishAuthorizedSetup(cfg, auth, params) {
     }
 }
 export async function setupAction(cfg) {
+    const startedAt = Date.now();
+    debugLog.cliCommand("membox setup");
     const existing = await readState();
     if (existing?.setup_complete) {
         console.log("Vault already set up. Use `openclaw membox status` to check.");
+        debugLog.cliCommandEnd("membox setup", true, Date.now() - startedAt);
         return;
     }
-    const auth = await authorizeDevice(cfg);
-    await runWithProvisioningRollback(auth, async (markProvisioned) => {
-        console.log("\nSet your vault passphrase (this encrypts your memory locally):");
-        console.log("Warning: This passphrase is NEVER sent to the server. If lost, use recovery materials.");
-        const passphrase = await readPassphraseWithConfirm("Vault passphrase: ");
-        const result = await finishAuthorizedSetup(cfg, auth, {
-            passphrase,
-            onRecoveryCode: async (recoveryCode) => {
-                console.log("\n========================================");
-                console.log("  SAVE YOUR RECOVERY CODE NOW!");
-                console.log("");
-                console.log(`  ${recoveryCode}`);
-                console.log("");
-                console.log("  Store it in a password manager or print.");
-                console.log("  Without it + passphrase, data is lost.");
-                console.log("========================================\n");
-            },
+    try {
+        const auth = await authorizeDevice(cfg);
+        await runWithProvisioningRollback(auth, async (markProvisioned) => {
+            console.log("\nSet your vault passphrase (this encrypts your memory locally):");
+            console.log("Warning: This passphrase is NEVER sent to the server. If lost, use recovery materials.");
+            debugLog.info("setup", "passphrase-prompt-start");
+            const passphrase = await readPassphraseWithConfirm("Vault passphrase: ");
+            debugLog.info("setup", "passphrase-prompt-complete");
+            const result = await finishAuthorizedSetup(cfg, auth, {
+                passphrase,
+                onRecoveryCode: async (recoveryCode) => {
+                    console.log("\n========================================");
+                    console.log("  SAVE YOUR RECOVERY CODE NOW!");
+                    console.log("");
+                    console.log(`  ${recoveryCode}`);
+                    console.log("");
+                    console.log("  Store it in a password manager or print.");
+                    console.log("  Without it + passphrase, data is lost.");
+                    console.log("========================================\n");
+                },
+            });
+            markProvisioned();
+            return result;
         });
-        markProvisioned();
-        return result;
-    });
+        debugLog.cliCommandEnd("membox setup", true, Date.now() - startedAt);
+    }
+    catch (error) {
+        debugLog.error("setup", `setup-action-failed error=${error instanceof Error ? error.message : String(error)}`);
+        debugLog.cliCommandEnd("membox setup", false, Date.now() - startedAt);
+        throw error;
+    }
 }

package/dist/src/constants.d.ts

@@ -1,5 +1,5 @@
 export declare const PLUGIN_ID = "membox";
-export declare const PLUGIN_VERSION = "0.1.0";
+export declare const PLUGIN_VERSION = "0.1.6";
 export declare const DEFAULT_SERVER_URL = "https://membox.cloud";
 export declare const API_PREFIX = "/api/v1";
 export declare const KEYCHAIN_SERVICE: string;

package/dist/src/constants.js

@@ -1,7 +1,7 @@
 import { homedir } from "node:os";
 import { join } from "node:path";
 export const PLUGIN_ID = "membox";
-export const PLUGIN_VERSION = "0.1.0";
+export const PLUGIN_VERSION = "0.1.6";
 export const DEFAULT_SERVER_URL = "https://membox.cloud";
 export const API_PREFIX = "/api/v1";
 export const KEYCHAIN_SERVICE = process.env.MEMBOX_KEYCHAIN_SERVICE || "membox.cloud";

package/dist/src/debug-logger.d.ts

@@ -4,10 +4,14 @@ export declare const debugLog: {
     error(component: string, msg: string): void;
     /** Log an API request (never logs tokens or ciphertext). */
     apiRequest(method: string, url: string): void;
+    apiRequestWithId(method: string, url: string, requestId: string): void;
     /** Log an API response (status + timing). */
-    apiResponse(method: string, url: string, status: number, ms: number): void;
+    apiResponse(method: string, url: string, status: number, ms: number, requestId?: string | null): void;
     /** Log an API error. */
-    apiError(method: string, url: string, error: unknown): void;
+    apiError(method: string, url: string, error: unknown, params?: {
+        requestId?: string | null;
+        bodySnippet?: string | null;
+    }): void;
     /** Log a crypto operation (never log key material). */
     crypto(op: string, detail?: string): void;
     /** Log a sync event. */
@@ -29,4 +33,5 @@ export declare const debugLog: {
     /** Log CLI command execution. */
     cliCommand(command: string): void;
     cliCommandEnd(command: string, success: boolean, ms: number): void;
+    state(component: string, msg: string): void;
 };

package/dist/src/debug-logger.js

@@ -16,6 +16,12 @@ function ensureDir() {
 function ts() {
     return new Date().toISOString();
 }
+function safeSnippet(value, max = 240) {
+    const normalized = value.replace(/\s+/g, " ").trim();
+    if (normalized.length <= max)
+        return normalized;
+    return `${normalized.slice(0, max - 1)}...`;
+}
 // Synchronous write is acceptable for debug/联调 use — keeps log ordering
 // deterministic and avoids async complexity. Not intended for production.
 function write(level, component, msg) {
@@ -46,16 +52,25 @@ export const debugLog = {
         const safeUrl = url.replace(/access_token=[^&]+/g, "access_token=***");
         write("INFO", "api-client", `→ ${method} ${safeUrl}`);
     },
+    apiRequestWithId(method, url, requestId) {
+        const safeUrl = url.replace(/access_token=[^&]+/g, "access_token=***");
+        write("INFO", "api-client", `→ ${method} ${safeUrl} request_id=${requestId}`);
+    },
     /** Log an API response (status + timing). */
-    apiResponse(method, url, status, ms) {
+    apiResponse(method, url, status, ms, requestId) {
         const safeUrl = url.replace(/access_token=[^&]+/g, "access_token=***");
-        write("INFO", "api-client", `← ${status} ${method} ${safeUrl} (${ms}ms)`);
+        const suffix = requestId ? ` request_id=${requestId}` : "";
+        write("INFO", "api-client", `← ${status} ${method} ${safeUrl} (${ms}ms)${suffix}`);
     },
     /** Log an API error. */
-    apiError(method, url, error) {
+    apiError(method, url, error, params) {
         const safeUrl = url.replace(/access_token=[^&]+/g, "access_token=***");
         const msg = error instanceof Error ? error.message : String(error);
-        write("ERROR", "api-client", `✗ ${method} ${safeUrl} — ${msg}`);
+        const requestId = params?.requestId ? ` request_id=${params.requestId}` : "";
+        const snippet = params?.bodySnippet
+            ? ` body="${safeSnippet(params.bodySnippet)}"`
+            : "";
+        write("ERROR", "api-client", `✗ ${method} ${safeUrl}${requestId} — ${msg}${snippet}`);
     },
     /** Log a crypto operation (never log key material). */
     crypto(op, detail) {
@@ -105,4 +120,7 @@ export const debugLog = {
         const status = success ? "ok" : "failed";
         write("INFO", "cli", `command-end: ${command} [${status}] (${ms}ms)`);
     },
+    state(component, msg) {
+        write("INFO", component, msg);
+    },
 };

package/dist/src/store/pending-setup-secrets.js

@@ -1,6 +1,7 @@
 import { chmod, mkdir, readFile, rename, unlink, writeFile } from "node:fs/promises";
 import { dirname, join } from "node:path";
 import { PENDING_SETUP_SECRETS_FILE, resolveStateRoot } from "../constants.js";
+import { debugLog } from "../debug-logger.js";
 function toB64(data) {
     return Buffer.from(data).toString("base64");
 }
@@ -26,6 +27,7 @@ async function writeFileState(state) {
     await writeFile(tmp, JSON.stringify(state, null, 2), { mode: 0o600 });
     await rename(tmp, path);
     await chmod(path, 0o600).catch(() => { });
+    debugLog.state("state", `pending-setup-secrets-write refresh_token_present=${Boolean(state.refresh_token)}`);
 }
 export async function storePendingSetupDeviceKeys(deviceKeys) {
     const existing = await readFileState();
@@ -70,4 +72,5 @@ export async function getPendingSetupRefreshToken() {
 }
 export async function clearPendingSetupSecretsFile() {
     await unlink(secretsPath()).catch(() => { });
+    debugLog.state("state", "pending-setup-secrets-delete");
 }

package/dist/src/store/pending-setup.js

@@ -1,13 +1,16 @@
 import { readFile, writeFile, mkdir, rename, unlink } from "node:fs/promises";
 import { join, dirname } from "node:path";
 import { PENDING_SETUP_FILE, resolveStateRoot } from "../constants.js";
+import { debugLog } from "../debug-logger.js";
 function pendingSetupPath() {
     return join(resolveStateRoot(), PENDING_SETUP_FILE);
 }
 export async function readPendingSetup() {
     try {
         const raw = await readFile(pendingSetupPath(), "utf-8");
-        return JSON.parse(raw);
+        const parsed = JSON.parse(raw);
+        debugLog.state("state", `pending-setup-read status=${parsed.status} user_code=${parsed.user_code} expires_at=${parsed.expires_at}`);
+        return parsed;
     }
     catch {
         return null;
@@ -19,9 +22,11 @@ export async function writePendingSetup(state) {
     const tmp = `${path}.tmp.${Date.now()}`;
     await writeFile(tmp, JSON.stringify(state, null, 2));
     await rename(tmp, path);
+    debugLog.state("state", `pending-setup-write status=${state.status} user_code=${state.user_code} expires_at=${state.expires_at}`);
 }
 export async function deletePendingSetup() {
     await unlink(pendingSetupPath()).catch(() => { });
+    debugLog.state("state", "pending-setup-delete");
 }
 export function isPendingSetupExpired(state) {
     if (state.status !== "pending") {

package/dist/src/sync/downloader.js

@@ -2,6 +2,7 @@ import { unwrapDEK } from "../crypto/keys.js";
 import { decrypt } from "../crypto/aes-gcm.js";
 import { computeSha256Hex, serializeAad } from "../crypto/manifest.js";
 import { getManifest, downloadBlob } from "../api/sync.js";
+import { debugLog } from "../debug-logger.js";
 function fromB64(s) {
     return new Uint8Array(Buffer.from(s, "base64"));
 }
@@ -10,6 +11,7 @@ function fromB64(s) {
  * Fetch manifest → download blobs → unwrap DEK → decrypt content → validate hash.
  */
 export async function downloadAndDecrypt(params) {
+    debugLog.syncDownloadStart(params.objectId);
     // Fetch manifest
     const { manifest } = await getManifest(params.client, params.objectId, params.version);
     const aadBytes = serializeAad(manifest.aad);
@@ -60,6 +62,7 @@ export async function downloadAndDecrypt(params) {
                 throw new Error(`Content hash mismatch: expected ${metadata.content_sha256}, got ${actualSha256}`);
             }
         }
+        debugLog.syncDownloadEnd(params.objectId, metadata.logical_path, manifest.object_version);
         return {
             logicalPath: metadata.logical_path,
             content,
@@ -68,6 +71,7 @@ export async function downloadAndDecrypt(params) {
         };
     }
     finally {
+        debugLog.cryptoDecryptDone(params.objectId);
         dek.fill(0);
     }
 }

package/dist/src/sync/uploader.js

@@ -3,6 +3,7 @@ import { generateDEK, wrapDEK } from "../crypto/keys.js";
 import { encrypt } from "../crypto/aes-gcm.js";
 import { buildManifest, computeSha256Hex, serializeAad } from "../crypto/manifest.js";
 import { uploadBlob, commitObject } from "../api/sync.js";
+import { debugLog } from "../debug-logger.js";
 function toB64(d) {
     return Buffer.from(d).toString("base64");
 }
@@ -14,6 +15,8 @@ export async function uploadFile(params) {
     const objectId = params.objectId ?? randomUUID();
     const version = (params.objectVersion ?? 0) + 1;
     const dek = generateDEK();
+    debugLog.syncUploadStart(params.logicalPath, objectId);
+    debugLog.crypto("encrypt-start", `${params.logicalPath} v${version}`);
     try {
         const aad = {
             user_id: params.userId,
@@ -78,6 +81,8 @@ export async function uploadFile(params) {
         });
         // Commit manifest
         const commitResult = await commitObject(params.client, { manifest });
+        debugLog.cryptoEncryptDone(objectId);
+        debugLog.syncUploadEnd(params.logicalPath, objectId, commitResult.version);
         return { objectId: commitResult.object_id, version: commitResult.version, seq: commitResult.seq };
     }
     finally {

package/openclaw.plugin.json

@@ -2,7 +2,7 @@
   "id": "membox",
   "name": "Membox Vault",
   "description": "Zero-knowledge encrypted memory sync for OpenClaw",
-  "version": "0.1.4",
+  "version": "0.1.6",
   "configSchema": {
     "type": "object",
     "additionalProperties": false,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@membox-cloud/membox",
-  "version": "0.1.4",
+  "version": "0.1.6",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",