@zktx.io/sui-mcp 0.7.0 → 0.8.1

package/dist/core/session/settingsWorkflow.js

@@ -1,6 +1,6 @@
 import { randomUUID } from "node:crypto";
 import { basename, dirname } from "node:path";
-import { TextDecoder } from "node:util";
+import { TextDecoder, isDeepStrictEqual } from "node:util";
 import { LocalDataError } from "../activity/localDataTypes.js";
 import { settingsInputError, SETTINGS_REPLACEMENT_BLOCKED_MESSAGE } from "./settingsInputError.js";
 import { SETTINGS_APPLIES_AFTER_RESTART } from "../preferences/preferencesStore.js";
@@ -10,7 +10,7 @@ import { DEFAULT_SESSION_TTL_MS } from "./localSession.js";
 import { isSettingsDownloadFile, settingsDownloadPath } from "./settingsFileIdentity.js";
 import { SettingsDownloadPathExists, settingsFileDigest, decodeSettingsChunk } from "./settingsFileStore.js";
 import { settingsIdentity } from "./sqliteSettingsWorkflowStore.js";
-import { SettingsConflict, settingsDownload, isSettingsDownloadFileAction, settingsViewSchema, endpointPreparationSchema, storedRestoreCheckSchema, retainedBackupRejection, permitsBackupRecheck } from "./settingsOperation.js";
+import { SettingsConflict, settingsCardInputSchema, settingsDownload, isSettingsDownloadFileAction, settingsViewSchema, endpointPreparationSchema, storedRestoreCheckSchema, retainedBackupRejection, permitsBackupRecheck } from "./settingsOperation.js";
 export const DOWNLOAD_RETRY_WINDOW_MS = DEFAULT_SESSION_TTL_MS;
 export class SettingsWorkflow {
     options;
@@ -29,7 +29,29 @@ export class SettingsWorkflow {
             runtimeEvent: (event) => this.runtimeEvent(event), readyPublished: (runId) => this.readyPublished(runId) });
     }
     get records() { this.options.assertCurrent(); return this.options.records; }
-    create(record) { this.records.create(record); }
+    async create(record) {
+        const input = settingsCardInputSchema.parse(record.state.input);
+        if (!input.operationStatus) {
+            this.records.create(record);
+            return;
+        }
+        const operation = this.records.get(input.operationStatus.operationId);
+        if (!operation || operation.dataEpoch !== this.records.control().data_epoch) {
+            throw new SettingsConflict("This Settings request is not available in the current profile and server run.");
+        }
+        const original = this.records.cards.get(operation.cardId);
+        if (!original)
+            throw new SettingsConflict("This Settings request is unavailable.");
+        const download = settingsDownload(operation);
+        const targetId = download?.localSave?.attempts.find((a) => a.saveAttemptId === download.localSave?.currentSaveAttemptId)?.cardId ??
+            download?.attempts.find((a) => a.attemptId === download.currentAttemptId)?.cardId;
+        const target = targetId ? this.records.cards.get(targetId) ?? original : original;
+        const current = await this.describe(target, true);
+        const { restoreCheck: _restoreCheck, ...status } = current.data;
+        const data = { ...status, allowedActions: [], observe: false,
+            ...(current.data.download ? { download: { ...current.data.download, allowedFileActions: [] } } : {}) };
+        this.records.cards.create({ ...record, state: { ...record.state, state: "closed", reason: "completed", data } });
+    }
     operationKind(record) { return this.records.forCard(record).draft?.kind; }
     recoverOwner() {
         this.records.transaction(() => {
@@ -51,25 +73,37 @@ export class SettingsWorkflow {
                 const card = this.records.cards.get(operation.cardId);
                 if (!card)
                     continue;
-                const verifyExport = operation.draft?.kind === "export_local_data" && file?.role === "export" && !!operation.admittedAt;
                 const result = { outcome: "interrupted", recordedAt: this.now().toISOString(),
                     message: operation.admittedAt
                         ? "Sui MCP restarted before this confirmed change finished. It will not be repeated. Check the result of the original request separately."
                         : "Sui MCP restarted before you confirmed this change. It will not be repeated." };
-                this.records.db.prepare(`UPDATE settings_operations SET owner_id=?,phase=?,result_json=?,checkpoint=? WHERE operation_id=?`)
-                    .run(this.records.ownerId, verifyExport ? "executing" : "terminal", verifyExport ? null : JSON.stringify(result), verifyExport ? "verify_export_after_owner_change" : null, operation.operationId);
+                this.records.db.prepare(`UPDATE settings_operations SET owner_id=?,phase='terminal',result_json=? WHERE operation_id=?`)
+                    .run(this.records.ownerId, JSON.stringify(result), operation.operationId);
                 const reason = card.state.reason ?? (card.state.state === "ready" && Date.parse(card.state.expiresAt) <= this.now().getTime() ? "expired" : "server_restarted");
-                if (this.records.db.prepare(`UPDATE live_read_cards SET owner_id=?,state=?,reason=?,revision=revision+1
-          WHERE id=? AND owner_id=? AND token_hash=? AND revision=?`).run(this.records.ownerId, verifyExport ? "running" : "closed", verifyExport ? null : reason, card.state.cardId, card.ownerId, card.tokenHash, card.state.revision).changes !== 1) {
+                this.records.invalidateUpload(operation);
+                if (card.state.state !== "closed" && !this.records.cards.replace(card, { ...card, ownerId: this.records.ownerId,
+                    state: { ...card.state, state: "closed", reason, revision: card.state.revision + 1,
+                        data: this.records.resultView(operation, result) } }, this.now())) {
                     throw new SettingsConflict("The interrupted Settings card changed while its status was being updated.");
                 }
-                if (file?.role === "upload")
-                    this.records.writeFile({ ...file, invalidated: true });
                 this.records.db.prepare(`UPDATE settings_control SET active_operation_id=NULL,wallet_input_blocked=0,wallet_block_operation_id=NULL
           WHERE id=1 AND active_operation_id=?`).run(operation.operationId);
                 if (file)
                     this.records.releaseFileIO(file.fileId);
             }
+            const pendingCards = this.records.db.prepare("SELECT id FROM live_read_cards WHERE kind='settings' AND state!='closed' AND owner_id!=?")
+                .all(this.records.ownerId);
+            for (const { id } of pendingCards) {
+                const card = this.records.cards.get(id), operation = this.records.get(card.operationId);
+                if (!operation)
+                    throw new SettingsConflict("The interrupted Settings operation is unavailable.");
+                const result = { outcome: "interrupted", recordedAt: this.now().toISOString(),
+                    message: "This card ended when the server restarted. Check the original operation's current result in a new status card; no effect will be repeated." };
+                if (!this.records.cards.replace(card, { ...card, ownerId: this.records.ownerId,
+                    state: { ...card.state, state: "closed", reason: "server_restarted", revision: card.state.revision + 1,
+                        data: this.records.resultView(operation, result) } }, this.now()))
+                    throw new SettingsConflict("The interrupted Settings card changed during recovery.");
+            }
             const ioId = this.records.control().file_io_id;
             if (ioId) {
                 const file = this.records.file(ioId);
@@ -159,23 +193,8 @@ export class SettingsWorkflow {
             await this.cleanupTemporaryFiles();
         });
     }
-    async verifyPriorExport(operation) {
-        const file = operation.fileId ? this.records.file(operation.fileId) : undefined;
-        let result = { outcome: "interrupted", recordedAt: this.now().toISOString(),
-            message: "Sui MCP restarted and the backup file could not be checked. Open a new Settings card to create another backup." };
-        if (file) {
-            try {
-                await this.options.files.verifyExport(file);
-                result = { outcome: "completed", recordedAt: this.now().toISOString(), message: "The previously created local backup was verified.",
-                    details: { path: this.options.files.exportPath(file), filename: file.displayName, fileId: file.fileId, sha256: file.sha256, totalSize: file.totalSize } };
-            }
-            catch { }
-        }
-        this.options.assertCurrent();
-        this.retainResult(operation.operationId, result, false, file && result.outcome === "completed" ? { ...file, sealed: true, receivedSize: file.totalSize } : undefined);
-    }
     async readFile(record, fileId, offset, limit, attemptId) {
-        const operation = this.records.forCard(record), file = this.records.file(fileId);
+        const operation = this.records.forCard(record);
         if (operation.draft?.kind === "download_backup") {
             if (this.closing)
                 throw new SettingsConflict("This server is closing; the download cannot continue.");
@@ -204,13 +223,7 @@ export class SettingsWorkflow {
                 await this.cleanupTemporaryFiles(operation.operationId);
             }
         }
-        if (operation.result?.outcome !== "completed" || operation.draft?.kind !== "export_local_data" || operation.fileId !== fileId ||
-            !file || file.operationId !== operation.operationId || !file.sealed || file.invalidated || attemptId !== undefined)
-            throw new SettingsConflict("This completed backup is not available for download.");
-        const length = Math.min(limit, file.totalSize - offset);
-        const data = await this.options.files.readExportRange(file, offset, length);
-        this.options.assertCurrent();
-        return { file, offset, chunkBase64: data.toString("base64") };
+        throw new SettingsConflict("This Settings request does not provide a download.");
     }
     async startDownload(expected, input) {
         let bytes;
@@ -231,7 +244,7 @@ export class SettingsWorkflow {
             await this.trackDownloadIO(file.fileId, () => this.options.files.createDownload(file, data));
             this.options.assertCurrent();
             readyAt = this.now().toISOString();
-            result = { outcome: "completed", completionScope: "backup_snapshot", recordedAt: readyAt,
+            result = { outcome: "completed", completionScope: "backup_delivery", recordedAt: readyAt,
                 message: "The backup is ready for download. This does not confirm that a file was saved.",
                 details: { filename: file.displayName, fileId: file.fileId, sha256: file.sha256, totalSize: file.totalSize } };
         }
@@ -243,7 +256,7 @@ export class SettingsWorkflow {
                     const existing = this.records.file(file.fileId);
                     this.records.writeFile({ ...existing, invalidated: true, cleanup: "complete" });
                 });
-            result = { outcome: "failed", completionScope: "backup_snapshot", recordedAt: this.now().toISOString(),
+            result = { outcome: "failed", completionScope: "backup_delivery", recordedAt: this.now().toISOString(),
                 message: "The backup could not be prepared. Open a new Settings card to try again." };
         }
         this.finishedFileIO.add(file.fileId);
@@ -304,7 +317,8 @@ export class SettingsWorkflow {
             retained = { saveAttemptId, outcome };
             this.localSaveResults.set(file.operationId, retained);
         }
-        this.records.settleLocalSave(file.operationId, retained.saveAttemptId, retained.outcome);
+        const path = retained.outcome.status === "saved" ? this.options.files.localBackupPath(file) : undefined;
+        this.records.settleLocalSave(file.operationId, retained.saveAttemptId, retained.outcome, path ? { directory: dirname(path), filename: basename(path) } : undefined);
         this.localSaveResults.delete(file.operationId);
         this.scheduleDownloadExpiry();
         await this.cleanupTemporaryFiles(file.operationId);
@@ -352,9 +366,9 @@ export class SettingsWorkflow {
         if (draft.kind === "set_endpoint" || draft.kind === "restore_endpoint")
             return settingsIdentity({ ...common, target: this.options.resolveEndpoint(draft),
                 current: this.options.preferences.getLocalSettingSync(draft.endpoint === "grpc" ? "suiGrpcUrl" : "suiGraphqlUrl") });
-        if (draft.kind === "clear_read_address")
+        if (draft.kind === "set_wallet_networks")
             return settingsIdentity({ ...common,
-                current: this.records.db.prepare("SELECT * FROM active_account_context WHERE id=1").get() ?? null });
+                current: this.options.preferences.getLocalSettingSync("walletConnectionChains") });
         if (draft.kind === "import_local_data" || draft.kind === "reset_local_data")
             return settingsIdentity({ ...common,
                 userDataRevision: control.user_data_revision, file: operation.fileId ? this.records.file(operation.fileId) : null });
@@ -387,8 +401,8 @@ export class SettingsWorkflow {
         return previous;
     }
     requireConfirmation(record, operation) {
-        if (["export_local_data", "download_backup"].includes(operation.draft?.kind ?? ""))
-            throw new SettingsConflict("Open a new Settings card and use Download backup.");
+        if (["set_wallet_networks", "clear_read_address", "download_backup"].includes(operation.draft?.kind ?? ""))
+            throw new SettingsConflict("This action is applied by its explicit save or download request.");
         const replacing = operation.draft?.kind === "restart_wallet_service" && typeof operation.preparation?.supersedesOperationId === "string"
             ? operation.preparation.supersedesOperationId : undefined;
         this.records.requireAdmission(record, { action: "settings_confirm", operationId: operation.operationId,
@@ -469,8 +483,25 @@ export class SettingsWorkflow {
         }
         return file.sealed ? required("Check this backup again before restoring.") : { status: "receiving" };
     }
-    async describe(record) {
+    expireInput(record) {
+        if (record.state.state !== "ready" || Date.parse(record.state.expiresAt) > this.now().getTime())
+            return record;
+        const operation = this.records.forCard(record);
+        const result = { outcome: "interrupted", recordedAt: this.now().toISOString(),
+            message: record.state.input.backupDelivery ? "This delivery card expired. Ask in chat for a new delivery card if the backup is still available."
+                : "The time to confirm this Settings change has ended." };
+        if (record.state.input.backupDelivery) {
+            if (!this.records.cards.replace(record, { ...record, state: { ...record.state, state: "closed", reason: "expired",
+                    revision: record.state.revision + 1, data: this.records.resultView(operation, result) } }, this.now()))
+                throw new SettingsConflict("This delivery card changed before it could expire.");
+        }
+        else
+            this.records.finish(operation.operationId, result, undefined, "expired");
+        return this.records.cards.get(record.state.cardId);
+    }
+    async describe(record, currentOperation = false) {
         this.options.assertCurrent();
+        record = this.expireInput(record);
         let operation = this.records.forCard(record);
         this.observeLocalSave(operation);
         let downloadExpiryPending = false;
@@ -485,17 +516,13 @@ export class SettingsWorkflow {
         if (operation.result === undefined) {
             this.synchronize(operation.operationId);
             operation = this.records.get(operation.operationId);
-            if (operation.checkpoint === "verify_export_after_owner_change" && !operation.result)
-                await this.verifyPriorExport(operation);
             if (operation.draft?.kind === "restart_wallet_service" && operation.admittedAt) {
                 this.options.wallet.recoveryContext();
                 this.assertRecoveryRecorded();
             }
             this.records.transaction(() => {
-                record = this.records.cards.evaluate(record, () => this.now()).record;
-                if (record.state.state === "closed" && record.state.reason === "expired") {
-                    if (operation.fileId)
-                        this.invalidateFile(operation.fileId);
+                record = this.expireInput(record);
+                if (!record.state.input.backupDelivery && record.state.state === "closed" && record.state.reason === "expired") {
                     this.records.finish(operation.operationId, { outcome: "interrupted", recordedAt: this.now().toISOString(), message: "The time to confirm this Settings change has ended." });
                 }
             });
@@ -506,7 +533,7 @@ export class SettingsWorkflow {
         }
         catch (error) {
             this.options.assertCurrent();
-            if (!operation.result)
+            if (!operation.result && !settingsDownload(operation)?.readyAt)
                 throw error;
             downloadExpiryPending = true;
         }
@@ -524,12 +551,14 @@ export class SettingsWorkflow {
         const restoreCheck = operation.draft?.kind === "import_local_data" && !operation.result
             ? this.restoreCheck(operation, record, file) : undefined;
         const allowed = [];
-        if (record.state.state === "ready" && record.ownerId === this.records.ownerId && operation.dataEpoch === this.records.control().data_epoch && !operation.result) {
+        if (!record.state.input.backupDelivery && record.state.state === "ready" && record.ownerId === this.records.ownerId && operation.dataEpoch === this.records.control().data_epoch && !operation.result) {
             const fileIOAvailable = this.records.fileIOAvailable();
             if (fileIOAvailable) {
                 allowed.push("settings_select", "settings_cancel");
                 if (this.records.control().active_operation_id === null)
-                    allowed.push("settings_download_backup");
+                    allowed.push("settings_download_backup", "settings_save_wallet_networks");
+                if (facts?.readAddress && facts.readConnectionId && this.records.control().active_operation_id === null)
+                    allowed.push("settings_clear_read_address");
                 if (operation.draft)
                     allowed.push("settings_back");
             }
@@ -544,7 +573,7 @@ export class SettingsWorkflow {
                     (file && !file.invalidated || this.records.canReserveFileIO(operation.operationId)))
                     allowed.push("settings_begin_upload");
             }
-            else if (operation.phase !== "prepared" && operation.draft && !["export_local_data", "download_backup"].includes(operation.draft.kind) &&
+            else if (operation.phase !== "prepared" && operation.draft && !["set_wallet_networks", "clear_read_address", "download_backup"].includes(operation.draft.kind) &&
                 (operation.draft.kind !== "restart_wallet_service" || this.canPrepareRestart()))
                 allowed.push("settings_prepare");
             if (operation.phase === "uploading" && file && !file.invalidated && !file.sealed) {
@@ -570,32 +599,49 @@ export class SettingsWorkflow {
                     ...(localSave.failure ? { failure: localSave.failure } : {}), ...(localSave.savedAt ? { savedAt: localSave.savedAt } : {}) } } : {}),
             ...(downloadEnd ? { endReason: downloadEnd } : {}),
             ...(storedDownload.expiresAt ? { expiresAt: storedDownload.expiresAt, remainingMs: Math.max(0, Date.parse(storedDownload.expiresAt) - this.now().getTime()) } : {}),
-            allowedFileActions: currentDownloadOwner && !this.closing ? [
-                ...(storedDownload.readyAt ? ["settings_report_download"] : []),
-                ...(!downloadEnd && file && !file.invalidated && localSave?.status !== "saving" ? ["settings_cancel_download",
-                    ...(!localSave && storedDownload.readyAt ? ["settings_retry_download"] : []),
-                    ...(localSave && (localSave.status === "needs_consent" || localSave.status === "failed" && localSave.failure === "not_published") &&
-                        this.records.canReserveFileIO(operation.operationId) ? ["settings_store_backup"] : [])] : [])
+            allowedFileActions: currentDownloadOwner && record.state.state !== "closed" && !this.closing ? [
+                ...(storedDownload.readyAt && currentAttempt?.cardId === record.state.cardId ? ["settings_report_download"] : []),
+                ...(!downloadEnd && file && !file.invalidated && localSave?.status !== "saving" ? [
+                    ...(currentAttempt?.cardId === record.state.cardId ? ["settings_cancel_download"] : []),
+                    ...(record.state.state === "ready" && record.state.input.backupDelivery && !localSave && storedDownload.readyAt ? ["settings_retry_download"] : []),
+                    ...(record.state.state === "ready" && record.state.input.backupDelivery && localSave && (localSave.status === "needs_consent" || localSave.status === "failed" && localSave.failure === "not_published") &&
+                        this.records.canReserveFileIO(operation.operationId) ? ["settings_store_backup"] : [])
+                ] : [])
             ] : []
         } : undefined;
         if (storedDownload && !downloadExpiryPending)
             this.scheduleDownloadExpiry();
-        const cleanup = operation.result ? downloadExpiryPending ? "pending" : this.records.temporaryFileCleanup(operation.operationId) : undefined;
-        const backupPath = localSave?.status === "saved" && file ? this.options.files.localBackupPath(file)
-            : operation.draft?.kind === "export_local_data" && operation.result?.outcome === "completed" ? operation.result.details?.path : undefined;
-        const data = { kind: "settings", operationId: operation.operationId, phase: operation.phase, allowedActions: allowed,
-            observe: !operation.result && (["executing", "stopping", "starting"].includes(operation.phase) || restoreCheck?.status === "checking"),
+        const backupPath = localSave?.status === "saved" && file ? this.options.files.localBackupPath(file) : undefined;
+        const readingDownloadStatus = currentOperation && storedDownload !== undefined;
+        const activeDelivery = storedDownload && !currentOperation && record.state.state !== "closed";
+        const deliveryPending = storedDownload && (localSave?.status === "saving" || !downloadEnd &&
+            (!storedDownload.readyAt || !currentAttempt?.hostReport && !localSave));
+        const recordedResult = currentOperation && storedDownload
+            ? (deliveryPending ? undefined : this.records.downloadResult(operation))
+            : operation.result;
+        const cleanup = recordedResult ? downloadExpiryPending ? "pending" : this.records.temporaryFileCleanup(operation.operationId) : undefined;
+        const data = { kind: "settings", operationId: operation.operationId,
+            phase: readingDownloadStatus ? recordedResult ? "terminal" : "executing"
+                : activeDelivery ? record.state.state === "ready" ? "draft" : "executing" : operation.phase, allowedActions: readingDownloadStatus ? [] : allowed,
+            observe: !readingDownloadStatus && (activeDelivery ? !storedDownload.readyAt || localSave?.status === "saving" : !operation.result && (["executing", "stopping", "starting"].includes(operation.phase) || restoreCheck?.status === "checking")),
             ...(restoreCheck ? { restoreCheck } : {}), ...(download ? { download } : {}),
             ...(typeof backupPath === "string" ? { backupLocation: { directory: dirname(backupPath), filename: basename(backupPath) } } : {}),
             ...(operation.draft ? { draft: operation.draft } : {}), ...(operation.preparationId ? { preparationId: operation.preparationId } : {}),
-            ...(operation.preparation && !storedDownload ? { preparation: operation.preparation } : {}), ...(operation.result ? { result: operation.result } : {}),
-            ...(cleanup ? { temporaryFileCleanup: cleanup } : {}),
+            ...(operation.preparation && !storedDownload ? { preparation: operation.preparation } : {}), ...(recordedResult && !activeDelivery ? { result: recordedResult } : {}),
+            ...(cleanup && !activeDelivery ? { temporaryFileCleanup: cleanup } : {}),
             ...(file ? { file: { fileId: file.fileId, displayName: file.displayName, totalSize: file.totalSize, receivedSize: file.receivedSize, sha256: file.sha256, sealed: file.sealed, cleanup: file.cleanup } } : {}),
             ...(facts ? { facts } : {}), ...(operation.priorRunId ? { priorRunId: operation.priorRunId } : {}),
             ...(operation.nextRunId ? { nextRunId: operation.nextRunId } : {}),
             ...(operation.supersedesOperationId ? { supersedesOperationId: operation.supersedesOperationId } : {}),
             ...(operation.supersededByOperationId ? { supersededByOperationId: operation.supersededByOperationId } : {}) };
         assertNoForbiddenMcpFields(data);
+        if (!currentOperation && record.state.state === "closed" && record.state.data !== undefined)
+            return { record, data: settingsViewSchema.parse(record.state.data) };
+        if (!currentOperation && record.state.input.backupDelivery && downloadEnd) {
+            this.records.transaction(() => this.records.finishDownloadCard(operation.operationId, record.state.cardId));
+            record = this.records.cards.get(record.state.cardId);
+            return { record, data: settingsViewSchema.parse(record.state.data) };
+        }
         return { record, data: settingsViewSchema.parse(data) };
     }
     async act(expected, action) {
@@ -613,8 +659,39 @@ export class SettingsWorkflow {
             await this.continueDownload(expected, action);
             return;
         }
-        if (action.action === "settings_select" && ["export_local_data", "download_backup"].includes(action.draft.kind)) {
-            throw new SettingsConflict("Use Download backup to request a backup in one step.");
+        if (action.action === "settings_clear_read_address" || action.action === "settings_save_wallet_networks") {
+            const input = action;
+            if (stored.acceptedDigest === settingsIdentity(input))
+                return;
+            this.records.transaction(() => {
+                const { card, operation } = this.records.requireInput(expected, input.operationId);
+                this.records.requireFinalSlot();
+                const previous = input.action === "settings_save_wallet_networks" ? this.options.preferences.getWalletConnectionChainsSync() : undefined;
+                if (input.action === "settings_save_wallet_networks" && !isDeepStrictEqual(previous, input.expectedChains)) {
+                    throw new SettingsConflict("The saved networks changed. Check the current settings before saving your selection.");
+                }
+                this.records.claimFinal(operation.operationId);
+                const next = { operationId: operation.operationId, cardId: operation.cardId, ownerId: operation.ownerId,
+                    dataEpoch: operation.dataEpoch, phase: "executing", draft: input.action === "settings_clear_read_address"
+                        ? { kind: "clear_read_address" } : { kind: "set_wallet_networks", chains: input.chains },
+                    acceptedDigest: settingsIdentity(input), admittedAt: this.now().toISOString() };
+                this.records.write(operation, next, card, { ...card, acceptedInput: input,
+                    state: { ...card.state, state: "running", revision: card.state.revision + 1 } });
+                if (input.action === "settings_clear_read_address") {
+                    this.records.clearReadAddress(input.connectionId, input.account);
+                    this.records.finish(operation.operationId, { outcome: "completed", recordedAt: this.now().toISOString(),
+                        message: "The saved read address was cleared. Your wallet connection and transaction requests are unchanged." });
+                }
+                else {
+                    this.options.preferences.setLocalSettingSync("walletConnectionChains", input.chains, this.now());
+                    this.options.wallet.closeConnectionCardsWithChangedNetworks(input.chains);
+                    this.records.finish(operation.operationId, { outcome: "completed", recordedAt: this.now().toISOString(),
+                        message: "Wallet networks were saved. They apply to new connections; existing connections are unchanged.",
+                        details: { walletConnectionChains: input.chains, previousWalletConnectionChains: previous, appliesTo: "new_connections" } });
+                }
+            });
+            await this.cleanupTemporaryFiles(input.operationId);
+            return;
         }
         if (action.action === "settings_confirm" && stored.acceptedDigest === settingsIdentity(action))
             return;
@@ -638,13 +715,12 @@ export class SettingsWorkflow {
             await this.seal(expected, action);
             return;
         }
+        let selected;
         this.records.transaction(() => {
             const { card, operation } = this.records.requireInput(expected, "operationId" in action ? action.operationId : undefined);
             if (!this.records.fileIOAvailable())
                 throw new SettingsConflict("Wait for the file transfer to finish before changing your selection.");
             if (action.action === "settings_cancel") {
-                if (operation.fileId)
-                    this.invalidateFile(operation.fileId);
                 this.records.finish(operation.operationId, { outcome: "interrupted", recordedAt: this.now().toISOString(), message: "This Settings change was cancelled. Nothing was applied." });
                 return;
             }
@@ -658,29 +734,26 @@ export class SettingsWorkflow {
             }
             const next = this.withoutPreparation(operation);
             if (action.action === "settings_select") {
-                if (operation.fileId)
-                    this.invalidateFile(operation.fileId);
                 delete next.fileId;
                 delete next.preparation;
                 next.draft = action.draft;
                 next.phase = "draft";
             }
             this.records.write(operation, next, card);
+            if (action.action === "settings_select" && action.draft.kind !== "import_local_data")
+                selected = this.records.cards.get(card.state.cardId);
         });
         await this.cleanupTemporaryFiles(stored.operationId);
-    }
-    invalidateFile(id) {
-        const file = this.records.file(id);
-        if (file?.role === "upload")
-            this.records.writeFile({ ...file, invalidated: true, cleanup: "pending" });
+        if (selected)
+            await this.prepare(selected, stored.operationId);
     }
     async prepare(expected, id) {
         const initial = this.records.requireInput(expected, id);
         const draft = initial.operation.draft;
         if (!draft)
             throw new SettingsConflict("Choose what you want to change in Settings first.");
-        if (["export_local_data", "download_backup"].includes(draft.kind))
-            throw new SettingsConflict("Open a new Settings card and use Download backup.");
+        if (["set_wallet_networks", "clear_read_address", "download_backup"].includes(draft.kind))
+            throw new SettingsConflict("This action is applied by its explicit save or download request.");
         let preparation;
         if (draft.kind === "import_local_data") {
             await this.checkImport(expected, id);
@@ -746,8 +819,6 @@ export class SettingsWorkflow {
                     this.records.write(operation, { ...this.withoutPreparation(operation), phase: "uploading" }, card);
                 return;
             }
-            if (operation.fileId)
-                this.invalidateFile(operation.fileId);
             const fileId = randomUUID();
             file = { fileId, operationId: operation.operationId, role: "upload", relativePath: `.settings-staging/${fileId}.upload`, displayName: action.name,
                 totalSize: action.totalSize, receivedSize: 0, sha256: action.sha256, sealed: false, invalidated: false, cleanup: "pending" };
@@ -923,8 +994,8 @@ export class SettingsWorkflow {
         const initial = this.records.requireInput(expected, action.operationId), draft = initial.operation.draft;
         if (!draft || initial.operation.preparationId !== action.preparationId)
             throw new SettingsConflict("Review the current Settings change before confirming it.");
-        if (["export_local_data", "download_backup"].includes(draft.kind))
-            throw new SettingsConflict("Open a new Settings card and use Download backup.");
+        if (draft.kind === "download_backup" || draft.kind === "set_wallet_networks" || draft.kind === "clear_read_address")
+            throw new SettingsConflict("This action is applied by its explicit save or download request.");
         if (draft.kind === "restart_wallet_service") {
             this.restart(expected, action);
             return;
@@ -997,15 +1068,12 @@ export class SettingsWorkflow {
                     effectiveValueAtSave: prepared.effectiveValue, effectiveSourceAtSave: prepared.source,
                     appliesAfter: SETTINGS_APPLIES_AFTER_RESTART };
             }
-            else if (draft.kind === "clear_read_address")
-                this.options.activity.clearActiveAccountSync(this.now());
             else if (replacement)
                 details = this.options.localData.applyValidatedReplacement(imported, decisionTime, expected.state.cardId);
             this.records.finish(operation.operationId, { outcome: "completed", recordedAt: this.now().toISOString(),
                 message: endpoint ? "The network address was saved. This result describes the settings at save time."
-                    : draft.kind === "clear_read_address" ? "The default address for viewing assets was cleared. Your wallet connection and transaction requests are unchanged."
-                        : draft.kind === "import_local_data" ? "Local records were replaced. Restart the apps using Sui MCP before continuing."
-                            : "Local data was reset. This does not cancel a transaction on Sui or disconnect your wallet app.", details });
+                    : draft.kind === "import_local_data" ? "Local records were replaced. Restart the apps using Sui MCP before continuing."
+                        : "Local data was reset. This does not cancel a transaction on Sui or disconnect your wallet app.", details });
         });
         if (refused)
             throw refused;
@@ -1088,12 +1156,18 @@ export class SettingsWorkflow {
             if (retained.downloadReadyAt)
                 this.records.recordDownloadReady(id, retained.downloadReadyAt, DOWNLOAD_RETRY_WINDOW_MS);
             else if (this.records.get(id)?.draft?.kind === "download_backup" && retained.result.outcome !== "completed")
-                this.records.endDownload(id, "source_unavailable");
+                this.records.endDownload(id, "source_unavailable", retained.result);
             const fileId = retained.file?.fileId ?? this.records.get(id)?.fileId;
             if (fileId && this.finishedFileIO.has(fileId)) {
                 this.records.releaseFileIO(fileId);
                 settledFileId = fileId;
             }
+            if (retained.downloadReadyAt) {
+                this.records.releaseFinal(id);
+                return true;
+            }
+            if (this.records.get(id)?.draft?.kind === "download_backup")
+                return true;
             return this.records.finish(id, retained.result);
         });
         if (settledFileId)

package/dist/core/session/sqliteCardStore.js

@@ -30,11 +30,11 @@ export class SqliteCardRecordStore {
             let record = this.get(expected.state.cardId);
             if (!record || record.tokenHash !== expected.tokenHash || record.ownerId !== expected.ownerId)
                 throw new Error("Saved card access is unavailable.");
-            if (record.state.state === "ready" && Date.parse(record.state.expiresAt) <= now.getTime()) {
+            if (!["connect", "disconnect", "review", "settings"].includes(record.state.kind) && record.state.state === "ready" && Date.parse(record.state.expiresAt) <= now.getTime()) {
                 const next = { ...record, state: { ...record.state, state: "closed", reason: "expired", revision: record.state.revision + 1 } };
-                if (!this.replace(record, next))
+                if (!this.replace(record, next, now))
                     throw new Error("Card expiry could not be committed.");
-                record = next;
+                record = this.get(record.state.cardId);
             }
             return { record, evaluatedAt: now.toISOString() };
         }).immediate();
@@ -53,25 +53,45 @@ export class SqliteCardRecordStore {
         }).immediate();
     }
     create(record) {
+        if (record.state.state === "closed")
+            record = this.terminal(record);
         this.db.prepare(`INSERT INTO live_read_cards
       (id, owner_id, token_hash, kind, state, reason, error, revision, created_at, expires_at,
        input_json, accepted_input_json, result_json, receipt_display_json, scope, operation_id)
       VALUES (@id, @owner, @token, @kind, @state, @reason, @error, @revision, @created, @expires,
        @input, @accepted, @result, @display, @scope, @operation)`).run(values(record));
     }
-    replace(expected, next) {
-        return this.db.prepare(`UPDATE live_read_cards SET state=@state, reason=@reason, error=@error,
-      revision=@revision, input_json=@input, accepted_input_json=@accepted, result_json=@result,
-      receipt_display_json=@display, scope=@scope, operation_id=@operation
-      WHERE id=@id AND owner_id=@owner AND token_hash=@token AND revision=@expectedRevision
-        AND state=@expectedState`).run({ ...values(next), expectedRevision: expected.state.revision,
-            expectedState: expected.state.state }).changes === 1;
+    terminal(record) {
+        if (["connect", "disconnect", "review", "settings"].includes(record.state.kind) && record.state.data === undefined) {
+            throw new Error("The owning domain must supply the card's committed result.");
+        }
+        return record;
+    }
+    replace(expected, next, _at) {
+        if (expected.state.state === "closed")
+            return false;
+        return this.db.transaction(() => {
+            if (next.state.state === "closed")
+                next = this.terminal(next);
+            return this.db.prepare(`UPDATE live_read_cards SET owner_id=@owner,state=@state,reason=@reason,error=@error,
+        revision=@revision,input_json=@input,accepted_input_json=@accepted,result_json=@result,
+        receipt_display_json=@display,scope=@scope,operation_id=@operation
+        WHERE id=@id AND owner_id=@expectedOwner AND token_hash=@token AND revision=@expectedRevision
+          AND state=@expectedState`).run({ ...values(next), expectedOwner: expected.ownerId,
+                expectedRevision: expected.state.revision, expectedState: expected.state.state }).changes === 1;
+        }).immediate();
     }
     recover(ownerId, now) {
-        this.db.prepare(`UPDATE live_read_cards SET
-      reason=CASE WHEN state='ready' AND expires_at<=@now THEN 'expired' ELSE 'server_restarted' END,
-      state='closed', revision=revision+1, owner_id=@owner
-      WHERE state!='closed' AND owner_id!=@owner`).run({ owner: ownerId, now: now.toISOString() });
+        this.db.transaction(() => {
+            const ids = this.db.prepare("SELECT id FROM live_read_cards WHERE state!='closed' AND kind NOT IN ('connect','disconnect','review','settings') AND owner_id!=?").all(ownerId);
+            for (const { id } of ids) {
+                const record = this.get(id);
+                const reason = record.state.state === "ready" && Date.parse(record.state.expiresAt) <= now.getTime() ? "expired" : "server_restarted";
+                if (!this.replace(record, { ...record, ownerId, state: { ...record.state, state: "closed", reason, revision: record.state.revision + 1 } }, now)) {
+                    throw new Error("Card recovery could not be committed.");
+                }
+            }
+        }).immediate();
     }
 }
 function values(record) {

package/dist/core/session/sqliteSessionStore.js

@@ -5,11 +5,11 @@ import { INITIAL_CHAIN_OBSERVATION_STATUSES } from "./transactionRequest.js";
 export function insertLiveReviewSessionRow(db, session) {
     const serialized = serializeSessionForLiveReviewSessionRow(session);
     db.prepare(`INSERT INTO live_review_sessions
-       (id, token_hash, status, account, owner_id, review_revision, preparation_id, preparation_error, wallet_connection_id, wallet_connection_revision, current_attempt_id,
+       (id, token_hash, status, account, owner_id, review_revision, preparation_id, preparation_error, wallet_connection_id, wallet_grant_revision, current_attempt_id,
         plans_json, review_state_json,
         created_at, expires_at, last_activity_at, revision, write_contract_version)
      VALUES
-       (@id, @tokenHash, @status, @account, @ownerId, @reviewRevision, @preparationId, @preparationError, @walletConnectionId, @walletConnectionRevision, @currentAttemptId,
+       (@id, @tokenHash, @status, @account, @ownerId, @reviewRevision, @preparationId, @preparationError, @walletConnectionId, @walletGrantRevision, @currentAttemptId,
         @plansJson, @reviewStateJson,
         @createdAt, @expiresAt, @lastActivityAt, 0, @writeContractVersion)`).run(serialized);
 }
@@ -25,7 +25,7 @@ export function updateLiveReviewSessionRow(db, expectedRevision, session) {
            preparation_id = @preparationId,
            preparation_error = @preparationError,
            wallet_connection_id = @walletConnectionId,
-           wallet_connection_revision = @walletConnectionRevision,
+           wallet_grant_revision = @walletGrantRevision,
            current_attempt_id = @currentAttemptId,
            plans_json = @plansJson,
            review_state_json = @reviewStateJson,
@@ -133,7 +133,7 @@ export function sessionFromLiveReviewSessionRow(row) {
         ownerId: row.owner_id,
         reviewRevision: row.review_revision,
         ...(row.wallet_connection_id === null ? {} : { walletConnectionId: row.wallet_connection_id }),
-        ...(row.wallet_connection_revision === null ? {} : { walletConnectionRevision: row.wallet_connection_revision }),
+        ...(row.wallet_grant_revision === null ? {} : { walletGrantRevision: row.wallet_grant_revision }),
         ...(row.preparation_error === null ? {} : { preparationError: row.preparation_error }),
         ...(row.preparation_id === null ? {} : { preparationId: row.preparation_id }),
         ...(row.current_attempt_id === null ? {} : { currentAttemptId: row.current_attempt_id })
@@ -150,7 +150,7 @@ export function serializeSessionForLiveReviewSessionRow(session) {
         preparationId: session.preparationId ?? null,
         preparationError: session.preparationError ?? null,
         walletConnectionId: session.walletConnectionId ?? null,
-        walletConnectionRevision: session.walletConnectionRevision ?? null,
+        walletGrantRevision: session.walletGrantRevision ?? null,
         currentAttemptId: session.currentAttemptId ?? null,
         plansJson: JSON.stringify(session.plans),
         reviewStateJson: session.reviewState ? JSON.stringify(session.reviewState) : null,