@zktx.io/sui-mcp 0.5.0 → 0.6.1

package/dist/core/session/sqliteWalletWorkflowStore.js

@@ -10,7 +10,7 @@ import { reviewStateOutputSchema } from "../action/schemas.js";
 import { LIVE_REVIEW_SESSION_WRITE_CONTRACT_VERSION } from "./liveReviewSessionContract.js";
 import { SqliteCardRecordStore } from "./sqliteCardStore.js";
 import { receiptDisplaySchema } from "./cardSession.js";
-import { isOwnedConnectedWallet, walletConnectionSelection, walletConnectionSchema, SUI_MAINNET_WALLET_CHAIN, SUI_SIGN_TRANSACTION_METHOD } from "./walletConnection.js";
+import { isOwnedConnectedWallet, walletConnectionSelection, walletConnectionSchema, walletRecoveryImpactSchema, SUI_MAINNET_WALLET_CHAIN, SUI_SIGN_TRANSACTION_METHOD } from "./walletConnection.js";
 import { SIGNATURE_WAIT_MS, CHAIN_RECEIPT_LOOKUP_MAX_AGE_MS, INITIAL_CHAIN_OBSERVATION_STATUSES, isInitialChainObservation, transactionRequestSchema, transactionExecutionSummarySchema, requestTransitions } from "./transactionRequest.js";
 export class WorkflowConflict extends Error {
     events;
@@ -24,16 +24,16 @@ const interruptionReasons = {
     wallet_change: "The wallet connection changed or became unavailable before submission. Nothing was submitted.",
     connection_conflict: "More than one wallet connection is present. Nothing was submitted.",
     disconnect_requested: "Wallet disconnection was requested before submission. Nothing was submitted.",
+    wallet_service_restarted: "The wallet service was restarted before submission. Nothing was submitted.",
     wallet_service_lost: "The wallet service stopped before submission. Nothing was submitted."
 };
 const preparationInterruptionReasons = {
     wallet_change: "The selected wallet connection changed.",
     connection_conflict: "More than one wallet connection is present. Disconnect the connections you no longer need, then update this review.",
     disconnect_requested: "Disconnection of the selected wallet was requested. Connect a wallet before updating this review.",
+    wallet_service_restarted: "The wallet service was restarted. Update this review before requesting approval.",
     wallet_service_lost: "The wallet service stopped. Restore the wallet connection and update this review before requesting approval."
 };
-/** Purpose-specific mutations on the activity owner's connection. Each method
- * commits card, request and public history together; no network work runs here. */
 export class SqliteWalletWorkflowStore {
     db;
     ownerId;
@@ -42,8 +42,16 @@ export class SqliteWalletWorkflowStore {
     materialStore;
     evaluateState;
     readActiveAccount;
+    readSdkSnapshot;
     cards;
-    constructor(db, ownerId, writeActiveAccount, clock, materialStore, evaluateState, readActiveAccount) {
+    runId;
+    setWalletRunId(runId) { this.runId = runId; }
+    assertWalletInputAllowed() {
+        if (this.db.prepare("SELECT wallet_input_blocked FROM settings_control WHERE id=1").get().wallet_input_blocked) {
+            throw new WorkflowConflict("Wallet input is blocked while the connection service is being recovered.");
+        }
+    }
+    constructor(db, ownerId, writeActiveAccount, clock, materialStore, evaluateState, readActiveAccount, readSdkSnapshot) {
         this.db = db;
         this.ownerId = ownerId;
         this.writeActiveAccount = writeActiveAccount;
@@ -51,9 +59,10 @@ export class SqliteWalletWorkflowStore {
         this.materialStore = materialStore;
         this.evaluateState = evaluateState;
         this.readActiveAccount = readActiveAccount;
+        this.readSdkSnapshot = readSdkSnapshot;
         this.cards = new SqliteCardRecordStore(db);
     }
-    evaluate(input) { return this.evaluateState(input); }
+    reconcileAndEvaluate(input) { return this.evaluateState(input); }
     currentCard(expected) {
         const current = this.cards.get(expected.state.cardId);
         if (!current || current.tokenHash !== expected.tokenHash || current.scope !== expected.scope || current.ownerId !== expected.ownerId ||
@@ -92,17 +101,32 @@ export class SqliteWalletWorkflowStore {
         return recovery;
     }
     recordWalletFailure(input) {
-        // Retried by the workflow until revocation is durably recorded. The SDK
-        // run is already fenced, so a failed write cannot preserve usable authority.
-        this.invalidateWalletRun("wallet_service_lost", new Date(input.observedAt));
+        this.invalidateWalletRun("wallet_service_lost", new Date(input.observedAt), input.runId);
     }
     publishWalletState() { this.publishAvailableWallets(); }
-    applyWalletObservation(snapshot, previous, ready) {
+    applyWalletObservation(snapshot, previous, ready, recordReady) {
         this.db.transaction(() => {
             for (const record of this.connections()) {
-                if (!record.topic || record.connection.status !== "connected")
+                if (!record.topic)
                     continue;
                 const observed = snapshot.sessions.find((item) => item.topic === record.topic);
+                if (record.connection.status !== "connected") {
+                    if ((ready || record.ownerId === this.ownerId && record.runId === snapshot.runId) &&
+                        observed?.status === "present" && !record.sdkPending &&
+                        !this.pendingDisconnect(record.connection.connectionId, record.ownerId)) {
+                        const transferred = record.ownerId !== this.ownerId || record.runId !== snapshot.runId;
+                        const changed = !isDeepStrictEqual(record.connection.accounts, observed.session.accounts) ||
+                            !isDeepStrictEqual(record.connection.methods, observed.session.methods) ||
+                            record.connection.expiresAt !== observed.session.expiresAt || record.connection.walletName !== observed.session.walletName;
+                        if (transferred)
+                            this.db.prepare("UPDATE live_wallet_connections SET owner_id=?,run_id=? WHERE id=?")
+                                .run(this.ownerId, snapshot.runId, record.connection.connectionId);
+                        if (transferred || changed)
+                            this.updateConnection(record.connection.connectionId, { accounts: observed.session.accounts,
+                                methods: observed.session.methods, expiresAt: observed.session.expiresAt, walletName: observed.session.walletName }, this.clock());
+                    }
+                    continue;
+                }
                 if (ready && observed?.status === "present" && !record.sdkPending && !this.pendingDisconnect(record.connection.connectionId, record.ownerId)) {
                     this.restoreConnection(observed.session, this.clock());
                 }
@@ -118,25 +142,38 @@ export class SqliteWalletWorkflowStore {
                 }
             }
             this.invalidateConflictingConnections(this.clock());
+            if (ready)
+                recordReady?.();
             if (ready)
                 this.publishAvailableWallets();
         }).immediate();
     }
-    invalidateWalletRun(cause, now = this.clock()) {
+    invalidateWalletRun(cause, now = this.clock(), runId) {
         this.db.transaction(() => {
+            const targets = new Set();
+            if (runId !== undefined) {
+                for (const row of this.db.prepare("SELECT connection_id FROM live_request_authority WHERE owner_id=? AND run_id=?")
+                    .all(this.ownerId, runId))
+                    targets.add(row.connection_id);
+                for (const row of this.db.prepare("SELECT wallet_connection_id FROM live_review_sessions WHERE owner_id=? AND preparation_run_id=? AND wallet_connection_id IS NOT NULL")
+                    .all(this.ownerId, runId))
+                    targets.add(row.wallet_connection_id);
+            }
             for (const record of this.connections()) {
-                if (record.ownerId !== this.ownerId)
+                if (record.ownerId !== this.ownerId || runId !== undefined && record.runId !== runId)
                     continue;
-                this.invalidateConnectionRequests(record.connection.connectionId, now, cause);
+                targets.add(record.connection.connectionId);
                 if (["connected", "awaiting_approval"].includes(record.connection.status))
                     this.updateConnection(record.connection.connectionId, {}, now);
             }
+            for (const id of targets)
+                this.invalidateConnectionRequests(id, now, cause, runId);
             this.publishAvailableWallets();
         }).immediate();
     }
     connection(id) {
         const row = this.db.prepare("SELECT * FROM live_wallet_connections WHERE id=?").get(id);
-        return row ? { connection: walletConnectionSchema.parse(JSON.parse(row.connection_json)), ownerId: row.owner_id,
+        return row ? { connection: walletConnectionSchema.parse(JSON.parse(row.connection_json)), ownerId: row.owner_id, ...(row.run_id === null ? {} : { runId: row.run_id }),
             sdkPending: row.sdk_pending === 1, ...(row.topic === null ? {} : { topic: row.topic }) } : undefined;
     }
     connections() {
@@ -146,20 +183,47 @@ export class SqliteWalletWorkflowStore {
     connectionView(connection) {
         return { ...connection, ...(this.pendingDisconnect(connection.connectionId) ? { pendingAction: "disconnect" } : {}) };
     }
-    connectionViews() {
-        return this.connections().filter((item) => item.ownerId === this.ownerId).map((item) => this.connectionView(item.connection));
+    connectionPresence(records, snapshot) {
+        const pendingConnectionIds = records.filter((item) => item.ownerId === this.ownerId &&
+            (item.sdkPending || !!this.pendingDisconnect(item.connection.connectionId))).map((item) => item.connection.connectionId);
+        if (!snapshot || snapshot.runId !== this.runId)
+            return { confirmed: false, connections: [], unrecorded: false, pendingConnectionIds };
+        const connections = [];
+        let unrecorded = false;
+        for (const session of snapshot.sessions) {
+            if (session.status !== "present")
+                continue;
+            const record = records.find((item) => item.topic === session.topic && item.ownerId === this.ownerId && item.runId === this.runId);
+            if (record)
+                connections.push({ connectionId: record.connection.connectionId, expiresAt: session.session.expiresAt });
+            else
+                unrecorded = true;
+        }
+        return { confirmed: true, connections, unrecorded, pendingConnectionIds };
+    }
+    readConnectionFacts(now) {
+        return this.db.transaction(() => {
+            const records = this.connections(), snapshot = this.readSdkSnapshot(), account = this.readActiveAccount();
+            return { evaluatedAt: now.toISOString(), activeAccount: account?.address, activeAccountConnectionId: account?.walletId,
+                connections: records.filter((item) => item.ownerId === this.ownerId).map((item) => this.connectionView(item.connection)),
+                connectionPresence: this.connectionPresence(records, snapshot),
+                ...(snapshot ? { walletObservation: { runId: snapshot.runId, sequence: snapshot.sequence, observedAt: snapshot.observedAt } } : {}) };
+        }).deferred();
     }
     connectionSelection(now = this.clock()) {
-        return walletConnectionSelection(this.connectionViews(), now.getTime(), this.readActiveAccount());
+        const facts = this.readConnectionFacts(now);
+        return walletConnectionSelection(facts.connections, now.getTime(), facts.connectionPresence, facts.activeAccount ? { address: facts.activeAccount, walletId: facts.activeAccountConnectionId } : undefined);
     }
     isUsableConnection(id, now = this.clock()) {
         return this.connectionSelection(now).connection?.connectionId === id;
     }
     invalidateConflictingConnections(now) {
-        const conflict = this.connectionSelection(now).conflict;
-        if (conflict)
-            for (const id of conflict.connectionIds)
-                this.invalidateConnectionRequests(id, now, "connection_conflict");
+        const selection = this.connectionSelection(now);
+        if (selection.conflict || selection.connectionReconciliationRequired)
+            for (const record of this.connections()) {
+                if (record.ownerId === this.ownerId)
+                    this.invalidateConnectionRequests(record.connection.connectionId, now, selection.conflict ? "connection_conflict" : "wallet_change");
+            }
     }
     settleConnection(id, source) {
         this.db.transaction(() => {
@@ -167,15 +231,15 @@ export class SqliteWalletWorkflowStore {
             if (!card || card.ownerId !== this.ownerId || card.operationId !== id || card.acceptedInput?.action !== source.action ||
                 card.acceptedInput.walletRunId !== source.runId)
                 return;
-            // A connection may progress from pairing to one admitted disconnect.
-            // That later operation owns sdk_pending even if its result is already
-            // visible and the original pairing's failed cleanup write arrives late.
             const disconnect = this.db.prepare(`SELECT id FROM live_read_cards WHERE owner_id=? AND scope='connect' AND operation_id=?
         AND json_extract(accepted_input_json,'$.action')='disconnect'`).get(this.ownerId, id);
-            if (disconnect && disconnect.id !== source.cardId)
+            if (source.action === "connect" && disconnect && disconnect.id !== source.cardId)
+                return;
+            const activeDisconnect = this.pendingDisconnect(id);
+            if (source.action === "disconnect" && activeDisconnect && activeDisconnect.state.cardId !== source.cardId)
                 return;
             const record = this.connection(id);
-            if (!record || record.ownerId !== this.ownerId)
+            if (!record || record.ownerId !== this.ownerId || record.runId !== source.runId)
                 return;
             if (source.action === "connect" && record.connection.status === "awaiting_approval") {
                 const status = source.unrecordedOutcome ?? "failed";
@@ -239,12 +303,10 @@ export class SqliteWalletWorkflowStore {
         if (card.state.kind === "review" && !session)
             throw new WorkflowConflict("The saved review is unavailable.");
         const connection = card.state.kind === "connect" && card.operationId ? this.connection(card.operationId)?.connection : undefined;
-        // Wallet-dependent commands already passed the workflow availability guard.
-        // This store checks DB eligibility; it does not measure SDK health.
-        const storedAccount = this.readActiveAccount(), activeAccount = storedAccount?.address, targetAccount = session?.account ?? activeAccount;
-        const facts = { evaluatedAt: now.toISOString(), ownerId: this.ownerId, record: card, session, request,
-            authority: request ? this.authority(request.attemptId) : undefined, connection, connections: this.connectionViews(),
-            walletAvailability: { status: "available" }, activeAccount, activeAccountConnectionId: storedAccount?.walletId,
+        const connectionFacts = this.readConnectionFacts(now), targetAccount = session?.account ?? connectionFacts.activeAccount;
+        const facts = { ...connectionFacts, ownerId: this.ownerId, record: card, session, request,
+            authority: request ? this.authority(request.attemptId) : undefined, connection,
+            walletAvailability: { status: "available" },
             busyForAccount: !!targetAccount && this.busyForAccount(targetAccount, now) };
         if (!workflowEligibility(facts).allowedActions.includes(action))
             throw new WorkflowConflict("That action is not available right now.");
@@ -305,19 +367,51 @@ export class SqliteWalletWorkflowStore {
       WHERE operation_id=@id`).run({ terminal: terminal ? 1 : 0, id: operationId });
     }
     publishConnection(connectionId, status) {
-        // Connection updates are not completion of every operation referencing it.
-        // In particular, session_update(connected) must not finish a pending disconnect.
+        const outcome = this.connection(connectionId)?.connection;
         this.db.prepare(`UPDATE live_read_cards SET revision=revision+1,
+      result_json=CASE WHEN state='running' AND json_extract(accepted_input_json,'$.action')='disconnect'
+        AND @disconnectTerminal THEN @outcome ELSE result_json END,
       reason=CASE WHEN state='running' AND
         CASE WHEN json_extract(accepted_input_json,'$.action')='disconnect'
           THEN @disconnectTerminal ELSE @connectionTerminal END THEN 'completed' ELSE reason END,
       state=CASE WHEN state='running' AND
         CASE WHEN json_extract(accepted_input_json,'$.action')='disconnect'
           THEN @disconnectTerminal ELSE @connectionTerminal END THEN 'closed' ELSE state END
-      WHERE scope='connect' AND operation_id=@id`).run({ id: connectionId,
+      WHERE scope='connect' AND operation_id=@id`).run({ id: connectionId, outcome: outcome ? JSON.stringify({ disconnectOutcome: outcome }) : null,
             disconnectTerminal: Number(status !== "connected" && status !== "awaiting_approval"),
             connectionTerminal: Number(status !== "awaiting_approval") });
     }
+    recoveryImpact(runId) {
+        return walletRecoveryImpactSchema.parse({
+            runId,
+            connections: this.connections().filter((record) => record.ownerId === this.ownerId && record.runId === runId)
+                .map((record) => ({ connectionId: record.connection.connectionId, revision: record.connection.revision,
+                status: record.connection.status, accounts: record.connection.accounts, walletName: record.connection.walletName,
+                sdkPending: record.sdkPending, disconnectPending: !!this.pendingDisconnect(record.connection.connectionId) })),
+            preparations: this.db.prepare(`SELECT id,revision,review_revision,preparation_id,wallet_connection_id FROM live_review_sessions
+        WHERE owner_id=? AND preparation_run_id=? AND status!='expired' ORDER BY id`).all(this.ownerId, runId),
+            requests: this.db.prepare(`SELECT r.attempt_id,r.revision,r.request_status,l.can_submit,l.sdk_pending,l.submit_pending,l.lookup_pending
+        FROM review_requests r JOIN live_request_authority l ON l.attempt_id=r.attempt_id
+        WHERE l.owner_id=? AND (l.run_id=? OR r.request_status IN ('submitting','awaiting_chain_result','outcome_unknown'))
+        ORDER BY r.attempt_id`).all(this.ownerId, runId)
+        });
+    }
+    recordRunExit(runId, parentProcessing = []) {
+        this.db.transaction(() => {
+            this.db.prepare(`UPDATE live_request_authority SET sdk_pending=0 WHERE owner_id=? AND run_id=? AND sdk_pending=1
+        AND attempt_id NOT IN (SELECT value FROM json_each(?))`).run(this.ownerId, runId, JSON.stringify(parentProcessing));
+            for (const record of this.connections()) {
+                if (record.ownerId !== this.ownerId || record.runId !== runId)
+                    continue;
+                const pending = this.pendingDisconnect(record.connection.connectionId);
+                if (pending)
+                    this.finishDisconnect(pending.state.cardId, record.connection.connectionId, false, this.clock());
+                else if (record.connection.status === "awaiting_approval")
+                    this.updateConnection(record.connection.connectionId, { status: "stopped", reason: "The wallet service ended before this connection was confirmed." }, this.clock(), undefined, false);
+                this.db.prepare("UPDATE live_wallet_connections SET sdk_pending=0 WHERE id=? AND run_id=? AND sdk_pending=1").run(record.connection.connectionId, runId);
+            }
+        }).immediate();
+    }
     publishAvailableWallets() {
         this.db.prepare("UPDATE live_read_cards SET revision=revision+1 WHERE owner_id=? AND kind IN ('connect','review') AND state='ready'").run(this.ownerId);
     }
@@ -328,17 +422,16 @@ export class SqliteWalletWorkflowStore {
     admitConnection(expected, input) {
         return this.db.transaction(() => {
             const now = this.clock();
+            this.assertWalletInputAllowed();
             this.expireConnections(now);
             const card = this.requireInput(expected, now);
             this.requireAction(card, "connect", now);
             const connection = walletConnectionSchema.parse({ connectionId: randomUUID(), status: "awaiting_approval", revision: 0,
                 accounts: [], methods: [], chain: SUI_MAINNET_WALLET_CHAIN, createdAt: now.toISOString(), updatedAt: now.toISOString(),
                 expiresAt: card.state.expiresAt });
-            this.db.prepare("INSERT INTO live_wallet_connections VALUES (?,?,?,?,?,?,?)")
-                .run(connection.connectionId, this.ownerId, connection.status, 0, null, 1, JSON.stringify(connection));
+            this.db.prepare("INSERT INTO live_wallet_connections (id,owner_id,status,revision,topic,sdk_pending,connection_json,run_id) VALUES (?,?,?,?,?,?,?,?)")
+                .run(connection.connectionId, this.ownerId, connection.status, 0, null, 1, JSON.stringify(connection), this.runId ?? null);
             this.consume(card, input, connection.connectionId);
-            // Every other live input observes the admitted connection before the SDK
-            // responds, so an older selection cannot bypass the one-connection rule.
             this.publishAvailableWallets();
             return this.connection(connection.connectionId);
         }).immediate();
@@ -372,20 +465,24 @@ export class SqliteWalletWorkflowStore {
         const existing = this.db.prepare("SELECT id FROM live_wallet_connections WHERE topic=?").get(session.topic);
         const id = existing?.id ?? randomUUID();
         const prior = existing ? this.connection(id) : undefined;
+        if (prior?.ownerId === this.ownerId && prior.runId === this.runId && prior.connection.status === "connected" && !prior.sdkPending &&
+            isDeepStrictEqual(prior.connection.accounts, session.accounts) && isDeepStrictEqual(prior.connection.methods, session.methods) &&
+            prior.connection.expiresAt === session.expiresAt && prior.connection.walletName === session.walletName)
+            return prior;
         const next = walletConnectionSchema.parse({ connectionId: id, status: "connected", revision: (prior?.connection.revision ?? -1) + 1,
             accounts: session.accounts, methods: session.methods, chain: session.chain,
             createdAt: prior?.connection.createdAt ?? now.toISOString(), updatedAt: now.toISOString(),
             expiresAt: session.expiresAt, walletName: session.walletName });
-        this.db.prepare(`INSERT INTO live_wallet_connections VALUES (?,?,?,?,?,?,?) ON CONFLICT(id) DO UPDATE SET
+        this.db.prepare(`INSERT INTO live_wallet_connections (id,owner_id,status,revision,topic,sdk_pending,connection_json,run_id) VALUES (?,?,?,?,?,?,?,?) ON CONFLICT(id) DO UPDATE SET
       owner_id=excluded.owner_id, status=excluded.status, revision=excluded.revision, topic=excluded.topic,
-      sdk_pending=0, connection_json=excluded.connection_json`).run(id, this.ownerId, next.status, next.revision, session.topic, 0, JSON.stringify(next));
+      sdk_pending=0, connection_json=excluded.connection_json,run_id=excluded.run_id`).run(id, this.ownerId, next.status, next.revision, session.topic, 0, JSON.stringify(next), this.runId ?? null);
         this.publishConnection(id, next.status);
-        // Restoring the SDK session never restores a cleared read-account context.
         return this.connection(id);
     }
     useAccount(expected, input, connectionId, account) {
         this.db.transaction(() => {
             const now = this.clock();
+            this.assertWalletInputAllowed();
             const card = this.requireInput(expected, now), connection = this.connection(connectionId);
             if (card.scope !== "connect" || !this.isUsableConnection(connectionId, now) || !isOwnedConnectedWallet(connection, this.ownerId, !!this.pendingDisconnect(connectionId)) ||
                 Date.parse(connection.connection.expiresAt) <= now.getTime() || !connection.connection.accounts.includes(account)) {
@@ -400,8 +497,10 @@ export class SqliteWalletWorkflowStore {
     admitDisconnect(expected, input, connectionId) {
         return this.db.transaction(() => {
             const now = this.clock();
+            this.assertWalletInputAllowed();
             const card = this.requireInput(expected, now), connection = this.connection(connectionId);
-            if (card.scope !== "connect" || !isOwnedConnectedWallet(connection, this.ownerId, !!this.pendingDisconnect(connectionId))) {
+            if (card.scope !== "connect" || !connection || connection.ownerId !== this.ownerId || connection.runId !== this.runId ||
+                connection.sdkPending || !this.connectionSelection(now).manageableConnectionIds.includes(connectionId)) {
                 throw new WorkflowConflict("The wallet connection is no longer available.");
             }
             this.requireAction(card, "disconnect", now);
@@ -415,7 +514,6 @@ export class SqliteWalletWorkflowStore {
     finishDisconnect(cardId, connectionId, succeeded, now) {
         this.db.transaction(() => {
             const pending = this.pendingDisconnect(connectionId);
-            // A session deletion event may have already completed this operation.
             if (pending?.state.cardId !== cardId)
                 return;
             this.updateConnection(connectionId, succeeded ? { status: "disconnected" } : {
@@ -456,6 +554,7 @@ export class SqliteWalletWorkflowStore {
     admitRequest(expected, input, material, selectedConnection, walletRunId) {
         const result = this.db.transaction(() => {
             const now = this.clock();
+            this.assertWalletInputAllowed();
             const binding = { reviewSessionId: material.reviewSessionId, planId: material.planId, account: material.account,
                 reviewRevision: material.reviewRevision, transactionDigest: material.reviewedTransactionDigest,
                 connectionId: selectedConnection.connectionId, connectionRevision: selectedConnection.revision };
@@ -469,9 +568,8 @@ export class SqliteWalletWorkflowStore {
             const artifacts = new SqlitePrivateReviewArtifactStore(this.db).get(material.reviewSessionId);
             const stored = this.materialStore.getTransactionMaterial(material.transactionMaterial, now);
             if (!current || !materialStillMatches(material, current, sessions.revision(current.id), artifacts, stored, now)) {
-                // Expected expiry commits its normal cleanup, but no request authority.
-                // A changed candidate is a conflict and must not invalidate newer data.
-                const evaluated = this.evaluateState({ expectedCard: card, candidate: { session: material.review, rowRevision: material.rowRevision,
+                const evaluated = this.evaluateState({ purpose: "review", reviewSessionId: material.reviewSessionId,
+                    readTarget: this.reviewReadTarget(material.reviewSessionId, card), expectedCard: card, candidate: { session: material.review, rowRevision: material.rowRevision,
                         artifacts: material.artifacts, material }, walletAvailability: { status: "available", walletRunId } }, now);
                 return new WorkflowConflict("The transaction details used by this review are no longer current.", evaluated.events);
             }
@@ -498,8 +596,8 @@ export class SqliteWalletWorkflowStore {
         (attempt_id,review_session_id,plan_id,review_revision,account_id,transaction_digest,review_state_json,request_status,revision,created_at,updated_at)
         VALUES (?,?,?,?,?,?,?,'awaiting_signature',0,?,?)`).run(id, review.id, binding.planId, binding.reviewRevision, account.id, binding.transactionDigest, review.review_state_json, now.toISOString(), now.toISOString());
             this.db.prepare(`INSERT INTO live_request_authority
-        (attempt_id,owner_id,connection_id,connection_revision,can_submit,sdk_pending,submit_pending,lookup_pending,signature_deadline)
-        VALUES (?,?,?,?,1,1,0,0,?)`).run(id, this.ownerId, binding.connectionId, binding.connectionRevision, new Date(Math.min(now.getTime() + SIGNATURE_WAIT_MS, Date.parse(review.expires_at))).toISOString());
+        (attempt_id,owner_id,connection_id,connection_revision,can_submit,sdk_pending,submit_pending,lookup_pending,signature_deadline,run_id)
+        VALUES (?,?,?,?,1,1,0,0,?,?)`).run(id, this.ownerId, binding.connectionId, binding.connectionRevision, new Date(Math.min(now.getTime() + SIGNATURE_WAIT_MS, Date.parse(review.expires_at))).toISOString(), walletRunId);
             this.db.prepare(`UPDATE live_review_sessions SET current_attempt_id=?, revision=revision+1, write_contract_version=? WHERE id=?`)
                 .run(id, LIVE_REVIEW_SESSION_WRITE_CONTRACT_VERSION, review.id);
             this.db.prepare("UPDATE review_sessions SET current_attempt_id=?, updated_at=? WHERE id=?").run(id, now.toISOString(), review.id);
@@ -590,8 +688,6 @@ export class SqliteWalletWorkflowStore {
             if (old.requestStatus === "awaiting_signature" && next !== old.requestStatus)
                 this.publishAvailableWallets();
             if (["stopped", "request_failed", "outcome_unknown", "completed"].includes(next)) {
-                // A historical attempt may finish while a newer review is preparing.
-                // Clean only the material still owned by this admitted revision.
                 for (const table of ["live_transaction_materials", "live_private_review_artifacts"]) {
                     this.db.prepare(`DELETE FROM ${table} WHERE review_session_id=? AND EXISTS
             (SELECT 1 FROM live_review_sessions WHERE id=? AND review_revision=? AND preparation_id IS NULL)`)
@@ -605,7 +701,8 @@ export class SqliteWalletWorkflowStore {
         return this.db.transaction(() => {
             const now = this.clock();
             const request = this.request(id), authority = this.authority(id);
-            if (!request || !authority || authority.owner_id !== this.ownerId || authority.can_submit !== 1 ||
+            if (!request || !authority || authority.owner_id !== this.ownerId || authority.can_submit !== 1 || authority.run_id !== (this.runId ?? null) ||
+                this.db.prepare("SELECT wallet_input_blocked FROM settings_control WHERE id=1").get().wallet_input_blocked !== 0 ||
                 request.requestStatus !== "awaiting_signature" || Date.parse(authority.signature_deadline) <= now.getTime())
                 return false;
             const connection = this.connection(authority.connection_id);
@@ -621,8 +718,6 @@ export class SqliteWalletWorkflowStore {
         this.db.transaction(() => {
             const now = this.clock();
             this.advanceRequestDeadlines(now, id);
-            // Observation may have finished, or its window may have closed, while
-            // submit was pending. A late response cannot reopen either outcome.
             if (this.request(id)?.requestStatus === "submitting")
                 this.transitionRequest(id, "awaiting_chain_result", now);
         }).immediate();
@@ -637,8 +732,6 @@ export class SqliteWalletWorkflowStore {
                 return request;
             if (request.requestStatus === "awaiting_signature")
                 return this.transitionRequest(id, cause === "wallet_service_lost" ? "request_failed" : "stopped", now, { reason: interruptionReasons[cause] });
-            // Once submitted, connection changes cannot revoke a transaction or the
-            // independent lookup of its digest. Only explicit user stopping ends observation.
             if (cause === "user_stop" && authority.observation_stopped === 0 &&
                 ["submitting", "awaiting_chain_result", "outcome_unknown"].includes(request.requestStatus)) {
                 this.db.prepare("UPDATE live_request_authority SET observation_stopped=1 WHERE attempt_id=?").run(id);
@@ -650,15 +743,14 @@ export class SqliteWalletWorkflowStore {
     resumeObservation(id) {
         this.db.prepare("UPDATE live_request_authority SET observation_stopped=0 WHERE attempt_id=? AND owner_id=?").run(id, this.ownerId);
     }
-    invalidateConnectionRequests(connectionId, now, cause) {
+    invalidateConnectionRequests(connectionId, now, cause, runId) {
         this.db.transaction(() => {
             const rows = this.db.prepare(`SELECT * FROM live_review_sessions v WHERE wallet_connection_id=? AND owner_id=? AND status!='expired'
+        AND (? IS NULL OR v.preparation_run_id=?)
         AND NOT EXISTS (SELECT 1 FROM review_requests r WHERE r.review_session_id=v.id AND r.review_revision=v.review_revision)`)
-                .all(connectionId, this.ownerId);
+                .all(connectionId, this.ownerId, runId ?? null, runId ?? null);
             for (const row of rows) {
                 const state = row.review_state_json ? JSON.parse(row.review_state_json) : undefined;
-                // Later session observations cannot rewrite why an already interrupted
-                // preparation ended. A new admitted preparation clears this error.
                 if (!row.preparation_id && row.preparation_error && !state?.transactionReviewData)
                     continue;
                 if (state) {
@@ -676,8 +768,8 @@ export class SqliteWalletWorkflowStore {
                 this.publishReview(row.id);
             }
         }).immediate();
-        for (const row of this.db.prepare("SELECT attempt_id FROM live_request_authority WHERE connection_id=? AND owner_id=?")
-            .all(connectionId, this.ownerId))
+        for (const row of this.db.prepare("SELECT attempt_id FROM live_request_authority WHERE connection_id=? AND owner_id=? AND (? IS NULL OR run_id=?)")
+            .all(connectionId, this.ownerId, runId ?? null, runId ?? null))
             this.stopWaiting(row.attempt_id, now, cause);
     }
     cancelInput(expected) {
@@ -693,6 +785,7 @@ export class SqliteWalletWorkflowStore {
     beginReviewPreparation(expected, reviewRevision, connection, account) {
         return this.db.transaction(() => {
             const now = this.clock();
+            this.assertWalletInputAllowed();
             const card = this.requireInput(expected, now);
             if (card.scope !== "review" || typeof card.state.input.reviewSessionId !== "string")
                 throw new WorkflowConflict("This card cannot update the review.");
@@ -713,8 +806,8 @@ export class SqliteWalletWorkflowStore {
             if (this.busyForAccount(selection.account, now) || !currentConnection.connection.accounts.includes(selection.account))
                 throw new WorkflowConflict("The review could not be updated with the selected wallet account.");
             const preparation = randomUUID();
-            this.db.prepare(`UPDATE live_review_sessions SET preparation_id=?,preparation_error=NULL,wallet_connection_id=?,wallet_connection_revision=?,revision=revision+1,write_contract_version=? WHERE id=?`)
-                .run(preparation, connection.connectionId, connection.revision, LIVE_REVIEW_SESSION_WRITE_CONTRACT_VERSION, id);
+            this.db.prepare(`UPDATE live_review_sessions SET preparation_id=?,preparation_run_id=?,preparation_error=NULL,wallet_connection_id=?,wallet_connection_revision=?,revision=revision+1,write_contract_version=? WHERE id=?`)
+                .run(preparation, this.runId ?? null, connection.connectionId, connection.revision, LIVE_REVIEW_SESSION_WRITE_CONTRACT_VERSION, id);
             this.publishReview(id);
             return preparation;
         }).immediate();
@@ -798,10 +891,11 @@ export class SqliteWalletWorkflowStore {
     }
 }
 export function hasUnsettledWalletWork(db, now = new Date()) {
-    return !!db.prepare(`SELECT 1 FROM live_request_authority l JOIN review_requests r ON r.attempt_id=l.attempt_id
+    return !!db.prepare("SELECT 1 FROM live_wallet_connections WHERE sdk_pending=1 LIMIT 1").get() ||
+        !!db.prepare(`SELECT 1 FROM live_request_authority l JOIN review_requests r ON r.attempt_id=l.attempt_id
     WHERE l.sdk_pending=1 OR l.submit_pending=1 OR l.lookup_pending=1
       OR (r.request_status IN (SELECT value FROM json_each(?)) AND (l.lookup_deadline IS NULL OR l.lookup_deadline>?)) LIMIT 1`)
-        .get(JSON.stringify(INITIAL_CHAIN_OBSERVATION_STATUSES), now.toISOString());
+            .get(JSON.stringify(INITIAL_CHAIN_OBSERVATION_STATUSES), now.toISOString());
 }
 export function readStoredTransactionRequest(db, id) {
     const row = db.prepare(`SELECT r.*, a.sui_address AS account, e.result_json FROM review_requests r

package/dist/core/session/status.js

@@ -32,8 +32,6 @@ export function isInteractionPendingReviewStatus(status) {
     return executionStatusCategory(status) !== "final";
 }
 export function isReviewInteractionPending({ hasReviewInput, request, progress }) {
-    // Historical preparation state is not proof that a live input remains.
-    // Consumed input, in turn, does not end its admitted request or observation.
     return hasReviewInput || progress.status !== "idle" || !!request && isRequestWaiting(request.requestStatus);
 }
 export function executionPollingHint() {
@@ -46,10 +44,10 @@ export function executionPollingHint() {
         recommendedIntervalSeconds: EXECUTION_POLLING_INTERVAL_SECONDS
     };
 }
-export function reviewStatusResponse({ session, request, walletAvailability, walletObservation, progress, connectionConflict }) {
+export function reviewStatusResponse({ session, request, walletAvailability, walletObservation, progress, connectionConflict, connectionReconciliationRequired }) {
     const pollingStatus = getExecutionPollingStatus(session, request);
     return {
-        walletAvailability, walletObservation, progress, connectionConflict,
+        walletAvailability, walletObservation, progress, connectionConflict, connectionReconciliationRequired,
         reviewSessionId: session.id, status: session.status, reviewRevision: session.reviewRevision,
         account: session.account, plans: session.plans, reviewState: session.reviewState,
         pollingStatus, statusCategory: executionStatusCategory(pollingStatus), pollingHint: executionPollingHint(),

package/dist/core/session/transactionMaterialStore.js

@@ -115,9 +115,6 @@ export class LocalTransactionMaterialStoreError extends Error {
         super(message);
     }
 }
-// Validate the store input and build the stored record (with cloned bytes). Shared
-// by every LocalTransactionMaterialStore implementation so validation never drifts
-// between the in-memory and SQLite backends.
 export function buildTransactionMaterialRecord(input, now = new Date()) {
     const account = parseSuiAddress(input.account);
     if (!account) {
@@ -158,7 +155,6 @@ export function buildTransactionMaterialRecord(input, now = new Date()) {
             : { redactedDiagnostics: structuredClone(input.redactedDiagnostics) })
     };
 }
-// Project the public (redacted) handle out of a stored record.
 export function toMaterialHandle(record) {
     return {
         materialId: record.materialId,

package/dist/core/session/transactionRequest.js

@@ -6,14 +6,10 @@ export const TRANSACTION_REQUEST_STATUSES = [
     "request_failed", "outcome_unknown", "completed"
 ];
 export const transactionRequestStatusSchema = z.enum(TRANSACTION_REQUEST_STATUSES);
-// The submission was admitted durably before external I/O. A failed follow-up
-// write must not remove its initial observation window or replacement guard.
 export const INITIAL_CHAIN_OBSERVATION_STATUSES = ["submitting", "awaiting_chain_result"];
 export function isInitialChainObservation(status) {
     return INITIAL_CHAIN_OBSERVATION_STATUSES.some((value) => value === status);
 }
-// This is the existing signing surface's local wait, independent of protocol
-// request expiry, card input expiry and the chain observation window.
 export const SIGNATURE_WAIT_MS = 90_000;
 export const CHAIN_RECEIPT_LOOKUP_MAX_AGE_MS = 10 * 60 * 1000;
 export const transactionExecutionSummarySchema = z.object({

package/dist/core/session/walletConnection.js

@@ -1,5 +1,6 @@
 import { z } from "zod";
 import { suiAddressStringSchema } from "../suiAddress.js";
+import { transactionRequestStatusSchema } from "./transactionRequest.js";
 export const SUI_MAINNET_WALLET_CHAIN = "sui:mainnet";
 export const SUI_SIGN_TRANSACTION_METHOD = "sui_signTransaction";
 export const WALLET_CONNECTION_POLL_SECONDS = 5;
@@ -45,6 +46,17 @@ export function workflowProgress(waiting, requiresWallet, availability) {
 export const walletConnectionStatusSchema = z.enum([
     "awaiting_approval", "connected", "rejected", "failed", "expired", "stopped", "disconnected"
 ]);
+export const walletRecoveryImpactSchema = z.object({
+    runId: z.string().uuid(),
+    connections: z.array(z.object({ connectionId: z.string().min(1), revision: z.number().int().nonnegative(),
+        status: walletConnectionStatusSchema, accounts: z.array(suiAddressStringSchema), walletName: z.string().optional(),
+        sdkPending: z.boolean(), disconnectPending: z.boolean() }).strict()),
+    preparations: z.array(z.object({ id: z.string().min(1), revision: z.number().int().nonnegative(),
+        review_revision: z.number().int().nonnegative(), preparation_id: z.string().nullable(), wallet_connection_id: z.string().nullable() }).strict()),
+    requests: z.array(z.object({ attempt_id: z.string().min(1), revision: z.number().int().nonnegative(),
+        request_status: transactionRequestStatusSchema, can_submit: z.number().int().min(0).max(1),
+        sdk_pending: z.number().int().min(0).max(1), submit_pending: z.number().int().min(0).max(1), lookup_pending: z.number().int().min(0).max(1) }).strict())
+}).strict();
 export const walletConnectionSchema = z.object({
     connectionId: z.string().min(1),
     status: walletConnectionStatusSchema,
@@ -63,21 +75,27 @@ export const connectionConflictSchema = z.object({
     connectionIds: z.array(z.string().min(1)).min(2).refine((ids) => new Set(ids).size === ids.length)
 }).strict();
 export const CONNECTION_CONFLICT_MESSAGE = "More than one wallet connection is saved. Disconnect the connections you no longer need before continuing.";
+export const CONNECTION_RECONCILIATION_MESSAGE = "A wallet connection in the connection service is not recorded here. Remove the retained connection in your wallet app, then check its status. If needed, open Settings and use Troubleshooting to restart the connection service and inspect it again. Restarting does not approve an unrecorded connection.";
 export const assetReadAccountSchema = z.discriminatedUnion("status", [
     z.object({ status: z.literal("available"), account: suiAddressStringSchema }).strict(),
     z.object({ status: z.literal("address_required") }).strict()
 ]);
-// Management may name every recorded target. Account use requires exactly one
-// live connection and no connection operation still awaiting its outcome.
-export function walletConnectionSelection(connections, at, stored) {
+export function walletConnectionSelection(connections, at, presence, stored) {
     const connected = connections.filter((item) => item.status === "connected" && Date.parse(item.expiresAt) > at);
-    const pending = connections.some((item) => item.pendingAction || item.status === "awaiting_approval");
-    const connection = connected.length === 1 && !pending ? connected[0] : undefined;
+    const pending = presence.pendingConnectionIds.length > 0 || connections.some((item) => item.pendingAction || item.status === "awaiting_approval");
+    const presentIds = presence.connections.map((item) => item.connectionId);
+    const occupied = new Set([...connected.map((item) => item.connectionId), ...presentIds]);
+    const reconciliation = presence.confirmed && presence.unrecorded && !pending;
+    const connection = presence.confirmed && !presence.unrecorded && occupied.size === 1 && connected.length === 1 &&
+        presence.connections.some((item) => item.connectionId === connected[0].connectionId && Date.parse(item.expiresAt) > at) && !pending ? connected[0] : undefined;
     return {
-        ...(connected.length > 1 ? { conflict: { reason: "multiple_connections",
-                connectionIds: connected.map((item) => item.connectionId).sort() } } : {}),
+        ...(occupied.size > 1 ? { conflict: { reason: "multiple_connections",
+                connectionIds: [...occupied].sort() } } : {}),
+        ...(reconciliation ? { connectionReconciliationRequired: true } : {}),
+        manageableConnectionIds: connections.filter((item) => !presence.pendingConnectionIds.includes(item.connectionId) && !item.pendingAction && item.status !== "awaiting_approval" &&
+            (item.status === "connected" || presence.confirmed && presentIds.includes(item.connectionId))).map((item) => item.connectionId),
         ...(connection ? { connection } : {}),
-        pairingAllowed: connected.length === 0 && !pending,
+        pairingAllowed: presence.confirmed && !presence.unrecorded && occupied.size === 0 && !pending,
         assetReadAccount: connection && stored?.walletId === connection.connectionId && connection.accounts.includes(stored.address)
             ? { status: "available", account: stored.address } : { status: "address_required" }
     };
@@ -85,8 +103,6 @@ export function walletConnectionSelection(connections, at, stored) {
 export class WalletUserRejectedError extends Error {
     constructor() { super("The wallet request was rejected by the user."); }
 }
-// Shared recorded connection facts only. Each operation checks its own expiry,
-// account, method and revision requirements at its decision boundary.
 export function isOwnedConnectedWallet(record, ownerId, disconnectPending) {
     return !!record && record.ownerId === ownerId && record.connection.status === "connected" && !disconnectPending;
 }