@zktx.io/sui-mcp 0.5.0 → 0.6.1

package/dist/runtime/smokeReview.js

@@ -3,8 +3,6 @@ import { computeReviewStateWithPrivateArtifacts } from "../core/review/reviewCom
 export class SmokeReviewConfigError extends Error {
 }
 const requiredSwapInputs = ["SMOKE_SWAP_PROTOCOL", "SMOKE_SWAP_FROM_SYMBOL", "SMOKE_SWAP_TO_SYMBOL", "SMOKE_SWAP_AMOUNT_DISPLAY"];
-/** Optional read-only review computation. This never establishes a wallet
- * connection; the caller owns the explicit temporary read-account fixture. */
 export async function computeSmokeReview(options) {
     const { env, sessions, computation, account } = options;
     const rawSlippage = env.SMOKE_SWAP_MAX_SLIPPAGE_BPS;
@@ -16,8 +14,6 @@ export async function computeSmokeReview(options) {
         return { status: "not_run", notRunReason: "missing_env", requiredEnv: [...requiredSwapInputs] };
     if (missing.length)
         throw new SmokeReviewConfigError(`Partial account-bound swap smoke configuration; missing: ${missing.join(", ")}`);
-    // Preserve the utility's existing 50 bps CLI default; it is not a product
-    // recommendation or a silently selected protocol/settlement asset.
     const parsed = swapIntentInputSchema.safeParse({ type: "swap", protocol: env.SMOKE_SWAP_PROTOCOL,
         from: { symbol: env.SMOKE_SWAP_FROM_SYMBOL, amount: env.SMOKE_SWAP_AMOUNT_DISPLAY },
         to: { symbol: env.SMOKE_SWAP_TO_SYMBOL }, maxSlippageBps: Number(env.SMOKE_SWAP_MAX_SLIPPAGE_BPS ?? "50") });

package/dist/runtime/start.js

@@ -43,8 +43,6 @@ async function main() {
             grpcOverride: process.env.SUI_GRPC_URL ?? null, graphqlOverride: process.env.SUI_GRAPHQL_URL ?? null
         });
         void controlReady.catch(() => { });
-        // The SDK owns stdin from the start, including fragmented initialization
-        // and EOF while backend startup is pending. No second reader buffers bytes.
         stage = "stdio_start";
         bridge = await startSharedStdio({ stdio, port: bootConfig.reviewPort, control: controlReady, ready: backendReady,
             onError: (error) => logger.error("MCP transport failed", { error: error.message }) });

package/dist/runtime/suiTransactionGraphqlMapping.js

@@ -187,8 +187,6 @@ function executionStatusFromGraphql(value) {
         return "success";
     if (value === "FAILURE")
         return "failure";
-    // Null status can occur before checkpointed effects are available; unmapped
-    // provider enum values stay unknown until explicitly mapped.
     return "unknown";
 }
 function normalizeGraphqlTimestamp(value) {

package/dist/runtime/suiTransactionGraphqlQueries.js

@@ -211,9 +211,6 @@ async function queryGraphql(client, options) {
         const result = await client.query({ query: options.query, variables: options.variables ?? {} });
         if (result.errors && result.errors.length > 0) {
             const message = result.errors.map((error) => error.message).join("; ");
-            // The pinned SDK exposes provider GraphQL errors as messages here. Cursor
-            // rejection is intentionally detected conservatively and otherwise falls
-            // back to provider_error.
             throw new TransactionActivitySourceError(message.toLowerCase().includes("cursor") ? "cursor_invalid" : "provider_error", "Sui GraphQL query returned errors", { message });
         }
         if (!result.data) {

package/dist/runtime/walletConnectConfig.js

@@ -1,3 +1 @@
-// Product-owned public dApp identifier. All installations share this Relay project.
-// This is not a wallet credential and has no user configuration override.
 export const WALLETCONNECT_PROJECT_ID = "62c5f7d7917d3936258d4b0746c99cab";

package/dist/runtime/walletConnectStorage.js

@@ -2,9 +2,6 @@ import { existsSync, lstatSync, mkdirSync } from "node:fs";
 import { join } from "node:path";
 import { serialize, deserialize } from "node:v8";
 import Database from "better-sqlite3";
-// Restoration namespaces of pinned SignClient/Core 2.23.10. Request history,
-// pending requests, messages, unacknowledged envelopes and new namespaces are
-// intentionally volatile; they may contain transaction or signature material.
 const persistentKeys = new Set([
     "wc@2:core:0.3//keychain", "wc@2:core:0.3//pairing",
     "wc@2:core:0.3//subscription", "wc@2:core:0.3//expirer",
@@ -12,12 +9,11 @@ const persistentKeys = new Set([
 ]);
 const storageSchema = "CREATE TABLE sdk_sessions (key TEXT PRIMARY KEY, value BLOB NOT NULL)";
 function storageFormat(db) {
-    const version = db.pragma("user_version", { simple: true });
     const schema = db.prepare("SELECT type,name,sql FROM sqlite_schema WHERE name NOT LIKE 'sqlite_%' ORDER BY type,name")
         .all();
-    if (version === 0 && schema.length === 0)
+    if (schema.length === 0)
         return "empty";
-    if (version === 1 && schema.length === 1 && schema[0]?.type === "table" &&
+    if (schema.length === 1 && schema[0]?.type === "table" &&
         schema[0].name === "sdk_sessions" && schema[0].sql === storageSchema)
         return "current";
     throw new Error("WalletConnect storage format is unsupported.");
@@ -59,11 +55,8 @@ export function openWalletConnectStorage(dataDirectory) {
         if (storageFormat(db) === "empty") {
             db.transaction(() => {
                 db.exec(storageSchema);
-                db.pragma("user_version = 1");
             })();
         }
-        // There is exactly one SDK owner. FULL protects the session material that
-        // the SDK needs to resume an acknowledged connection after process exit.
         db.pragma("journal_mode = DELETE");
         db.pragma("synchronous = FULL");
     }
@@ -94,6 +87,5 @@ export function openWalletConnectStorage(dataDirectory) {
                 volatile.delete(key);
         }
     };
-    // Once injected, SDK timers own the storage until the owner process exits.
     return { storage, closeBeforeSdkUse: () => { volatile.clear(); db.close(); } };
 }

package/dist/runtime/walletConnectTransport.js

@@ -27,8 +27,6 @@ export async function createWalletConnectTransport(options) {
     if (!/^[0-9a-f]{32}$/i.test(options.projectId))
         throw new Error("WalletConnect project ID format is invalid.");
     const owner = openWalletConnectStorage(options.dataDirectory);
-    // SDK log bodies can contain pairing credentials and serialized requests.
-    // Product failure stages are recorded by the caller without these values.
     options.onSdkStart?.();
     const client = await (options.initialize ?? SignClient.init.bind(SignClient))({ projectId: options.projectId, metadata: { ...options.metadata, icons: [] },
         storage: owner.storage, logger: "silent", telemetryEnabled: false });
@@ -37,8 +35,6 @@ export async function createWalletConnectTransport(options) {
     const changed = (event) => { if (!stopped)
         for (const listener of listeners)
             listener(event.topic); };
-    // Pinned SignClient emits session_event without changing session.namespaces.
-    // Treat active account/chain changes as invalidation, not new authorization.
     const selectionChanged = (event) => {
         if (!stopped && ["accountsChanged", "chainChanged"].includes(event.params.event.name)) {
             for (const listener of listeners)
@@ -60,7 +56,6 @@ export async function createWalletConnectTransport(options) {
     const inspect = (topic) => {
         if (stopped)
             throw new Error("WalletConnect owner stopped.");
-        // A store failure is not evidence that the session disappeared.
         const session = client.session.getAll().find((item) => item.topic === topic);
         return session ? inspectValue(session) : { topic, status: "absent" };
     };
@@ -75,8 +70,6 @@ export async function createWalletConnectTransport(options) {
     return {
         async restore() {
             requireActive();
-            // A pending proposal is not an approved session and must not reappear as
-            // a new approval ceremony after owner replacement.
             for (const pairing of client.core.pairing.getPairings()) {
                 if (!pairing.active)
                     await client.core.pairing.disconnect({ topic: pairing.topic });
@@ -89,8 +82,6 @@ export async function createWalletConnectTransport(options) {
                         chains: [SUI_MAINNET_WALLET_CHAIN], methods: [SUI_SIGN_TRANSACTION_METHOD], events: ["accountsChanged", "chainChanged"]
                     } } });
             const approval = connecting.approval().then(sessionValue).catch((error) => { throw transportError(error); });
-            // Attach a rejection handler immediately; the backend records the same
-            // promise's outcome once the private QR has been associated with its row.
             void approval.catch(() => undefined);
             if (!connecting.uri)
                 throw new Error("The wallet pairing could not be prepared.");
@@ -121,8 +112,6 @@ export async function createWalletConnectTransport(options) {
             client.off("session_delete", changed);
             client.off("session_expire", changed);
             client.off("session_event", selectionChanged);
-            // SignClient has no supported complete in-process disposal. The runtime
-            // ends the owner process; it must not close injected storage under timers.
         }
     };
 }

package/dist/runtime/walletSdkChildRuntime.js

@@ -1,10 +1,9 @@
+import { SERVER_VERSION } from "../mcp/serverInfo.js";
 import { join } from "node:path";
 import { isDeepStrictEqual } from "node:util";
 import { WalletUserRejectedError } from "../core/session/walletConnection.js";
 import { acquireDataDirectoryOwner } from "./shared/ownerLease.js";
 import { walletCommandSchema, walletEventSchema } from "./walletSdkIpc.js";
-// Production and the real-SDK wire fixture run this same process lifecycle.
-// The factory is a code dependency, never a serialized command or setting.
 export function runWalletSdkChild(createTransport) {
     let init, transport;
     let sequence = 0, lastRequest = 0, ready = false, exiting = false;
@@ -19,7 +18,7 @@ export function runWalletSdkChild(createTransport) {
         process.send(walletEventSchema.parse(message), (error) => { if (error)
             exit(); });
     };
-    const envelope = () => ({ protocolVersion: 1, runId: init.runId });
+    const envelope = () => ({ packageVersion: SERVER_VERSION, runId: init.runId });
     const exit = () => { if (!exiting) {
         exiting = true;
         void ownership;
@@ -29,7 +28,6 @@ export function runWalletSdkChild(createTransport) {
         ready = false;
         if (init && !exiting)
             send({ ...envelope(), type: "failure", reason });
-        // Neither SDK cleanup nor a callback is a prerequisite for process exit.
         if (!exiting) {
             exiting = true;
             process.exit(1);
@@ -74,7 +72,6 @@ export function runWalletSdkChild(createTransport) {
     };
     const start = async (input) => {
         init = input;
-        // The child alone opens the SDK store; OS exit releases this separate lock.
         ownership = acquireDataDirectoryOwner(join(input.dataDirectory, "walletconnect", "sessions.sqlite"));
         send({ ...envelope(), type: "stage", stage: "sdk_start" });
         transport = await createTransport(input);
@@ -153,7 +150,6 @@ export function runWalletSdkChild(createTransport) {
         }
         if (!init || input.runId !== init.runId || input.requestId <= lastRequest)
             return;
-        // Reserve before awaiting anything, including a connect approval.
         lastRequest = input.requestId;
         void command(input).catch(() => fail("wallet_state_unavailable"));
     });

package/dist/runtime/walletSdkIpc.js

@@ -1,8 +1,9 @@
+import { SERVER_VERSION } from "../mcp/serverInfo.js";
 import { z } from "zod";
 import { suiAddressStringSchema } from "../core/suiAddress.js";
 import { walletRunIdSchema, walletStartStageSchema, walletSnapshotSchema, walletSessionObservationSchema, walletSessionSchema } from "../core/session/walletRuntime.js";
 import { walletUnavailableReasonSchema } from "../core/session/walletConnection.js";
-const envelope = z.object({ protocolVersion: z.literal(1), runId: walletRunIdSchema });
+const envelope = z.object({ packageVersion: z.literal(SERVER_VERSION), runId: walletRunIdSchema });
 const request = envelope.extend({ requestId: z.number().int().positive(), operationId: z.string().min(1) });
 export const walletCommandSchema = z.union([
     envelope.extend({ type: z.literal("init"), dataDirectory: z.string().min(1), projectId: z.string().regex(/^[0-9a-f]{32}$/i),

package/dist/runtime/walletSdkProcess.js

@@ -1,11 +1,10 @@
+import { SERVER_VERSION } from "../mcp/serverInfo.js";
 import { fork } from "node:child_process";
 import { randomUUID } from "node:crypto";
 import { isDeepStrictEqual } from "node:util";
 import { walletUnavailable, WalletUnavailableError, WalletUserRejectedError } from "../core/session/walletConnection.js";
 import { WalletRunInterruptedError, WalletReplacementFailedError } from "../core/session/walletRuntime.js";
 import { walletCommandSchema, walletEventSchema } from "./walletSdkIpc.js";
-/** Owns one SDK process. Business authority and all database transitions remain
- * in the workflow; a process event is never transaction approval. */
 export class WalletSdkProcess {
     options;
     run = this.newRun();
@@ -74,13 +73,12 @@ export class WalletSdkProcess {
             child.once("exit", () => this.exited(run));
             child.once("error", () => {
                 this.lose(run, this.failureReason());
-                // Failed spawn has no process and therefore cannot emit exit.
                 if (child.pid === undefined)
                     this.exited(run);
             });
             child.once("disconnect", () => { if (!run.fenced && !run.didExit)
                 this.lose(run, this.failureReason()); });
-            this.send(run, { protocolVersion: 1, runId: run.id, type: "init", dataDirectory: this.options.dataDirectory,
+            this.send(run, { packageVersion: SERVER_VERSION, runId: run.id, type: "init", dataDirectory: this.options.dataDirectory,
                 projectId: this.options.projectId, metadata: this.options.metadata });
         }
         catch {
@@ -92,7 +90,6 @@ export class WalletSdkProcess {
     send(run, message) {
         if (run !== this.run || run.fenced || this.closed || !run.child?.connected)
             throw new WalletRunInterruptedError(run.id);
-        // A false return means backpressure, not permission to repeat the command.
         run.child.send(walletCommandSchema.parse(message), (error) => { if (error)
             this.lose(run, "wallet_state_unavailable"); });
     }
@@ -270,8 +267,6 @@ export class WalletSdkProcess {
             if (this.closed || this.run !== old || this.replacement !== replacement)
                 throw new WalletRunInterruptedError(runId);
             const next = this.newRun();
-            // A failed reservation ends this attempt. Reads may save its failure,
-            // but only a new explicit admission may start another SDK process.
             beforeStart(next.id);
             this.run = next;
             this.state = this.starting(next.id, "process_start");
@@ -318,7 +313,7 @@ export class WalletSdkProcess {
             return new Promise((resolve, reject) => {
                 run.pending.set(requestId, { operationId, type: input.type, resolve, reject, ...approval });
                 try {
-                    this.send(run, { ...input, protocolVersion: 1, runId: run.id, requestId, operationId });
+                    this.send(run, { ...input, packageVersion: SERVER_VERSION, runId: run.id, requestId, operationId });
                 }
                 catch (error) {
                     run.pending.delete(requestId);

package/docs/AGENT_BEHAVIOR.md

@@ -4,7 +4,7 @@ This document is the MCP-exposed answer playbook for AI clients. It owns user-qu
 
 It does not define tool schemas or field contracts. Use `docs/MCP_TOOLS.md` for the MCP API reference, response fields, statuses, and follow-up fields.
 
-It is not the contributor rulebook and it is not enforcement. Development rules live in `AGENTS.md` and `docs/AGENT_DEVELOPMENT_POLICY.md`. Hard product boundaries live in code, schemas, allowlists, mainnet guards, and the local review layer.
+It is not the contributor rulebook and it is not enforcement. Development rules live in `AGENTS.md` and `docs/AGENT_DEVELOPMENT_POLICY.md` in the [source repository](https://github.com/zktx-mcp/sui-mcp). They are not installed MCP resources. Hard product boundaries live in code, schemas, allowlists, mainnet guards, and the local review layer.
 
 ## Support Matrix
 
@@ -311,7 +311,7 @@ For a connected-account-only read, use `session.get_interaction_status` to disti
 1. `account.get_active_account` reports the stored selection, with `source` and `setAt`. For current assets without a user-provided address, use `session.get_interaction_status.assetReadAccount` to check whether that selection is a usable default. If not, request an address only for tools that accept `account`; connected-account-only tools require the connection/account-selection flow. Do not infer current connection from the stored selection.
 2. An explicit connect/reconnect/disconnect/account replacement request opens an internal
    Connect card with `session.create_wallet_connection`: use `intent: connect` for requested pairing, `intent: disconnect` for requested disconnection, and `intent: manage` for inspection or account selection. The model must not call app-only actions on the user's behalf.
-For "disconnect my wallet", when the wallet service is available and the target is connected, open `session.create_wallet_connection` with `intent: disconnect`. For one connected target the card shows Confirm disconnect or Back directly; Back only returns to the connection view; it does not submit Cancel review or disconnect. The card starts no pairing. Do not substitute `account.clear_active_account`, claim disconnection is unsupported merely because there is no direct model-facing disconnect tool, or equate disconnection with revoking onchain permissions. If disconnection is already pending, read or wait on that exact card instead of opening another operation.
+For "disconnect my wallet", when the wallet service is available and the target is connected, open `session.create_wallet_connection` with `intent: disconnect`. For one connected target the card shows Confirm disconnect or Back directly; Back only returns to the connection view; it does not submit Cancel review or disconnect. The card starts no pairing. Do not substitute the Settings action to clear the default read address, claim disconnection is unsupported merely because there is no direct model-facing disconnect tool, or equate disconnection with revoking onchain permissions. If disconnection is already pending, read or wait on that exact card instead of opening another operation.
 
 3. `session.get_wallet_connection` and `session.wait_wallet_connection` use the
    returned cardId. An unsubmitted card needs input; waiting does not create a
@@ -347,12 +347,28 @@ them. `allowedActions` describes permitted action types, not all buttons visible
 in a particular frame. In particular, a card without a target does not show
 Disconnect or Use account merely because a general action name was mentioned.
 
-There is no service-restart button in Connect or Settings. If the service is
-unavailable or disconnection remains unresponsive, explain the operational
-procedure in the setup guide: fully quit all apps using Sui MCP, then
-reopen them. Closing only a non-owning app or a window may leave the shared
-backend running. Do not kill processes or repeatedly send wallet commands for
-the user, and do not report restart success before the new service is observed.
+Connection-service recovery belongs to Settings. When the service is unavailable
+or a connection operation remains unresponsive, open
+`settings.create_local_settings_session` on the user's request and direct them
+to Troubleshooting. The user inspects the affected run/requests and explicitly
+confirms Restart connection service; do not call app-only actions for them.
+A new Settings card can explicitly supersede a startup still pending. Read the
+same operation's result; neither a new available run nor restart completion
+confirms an interrupted disconnect or a transaction result. Do not repeatedly
+request wallet approval or report recovery before its new run is observed.
+`manageableConnectionIds` names exact disconnect targets, not usable wallet
+choices. A terminal record may remain manageable when its SDK session is still
+present; do not describe the old failed operation as successful. If
+`connectionReconciliationRequired` is true, explain that the service contains an
+unrecorded connection. Ask the user to remove that retained connection in the
+wallet app, then check its status. Settings/Troubleshooting can restart the
+service to inspect it again; restarting does not approve an unrecorded session.
+Do not infer a free pairing slot from a failed or expired record.
+
+If the parent or Settings itself cannot be reached, explain the full app exit
+procedure in the setup guide. All participating apps must quit; closing a peer
+or window can leave the owner alive. Full app restart is also required for
+stored endpoint or installation changes. Do not kill another app's processes.
 
 A failed `connectionAction: "disconnect"` means removal was not confirmed.
 Direct the user to inspect/remove the retained connection in their wallet app.
@@ -468,9 +484,27 @@ For `read.list_review_activity`, `dataScope.recordCount` is the full matching lo
 
 For `read.get_review_session_detail`, transition rows with `isNoOp: true` are repeated lifecycle observations where the stored status did not change. Mention them only as audit details; do not count them as extra funnel progress.
 
-For local settings or local data management, call `settings.create_local_settings_session` and tell the user to open the returned settings URL in the same machine's system browser.
-
-Do not call MCP tools to mutate settings directly; direct settings mutator tools are not exposed. Do not call clearing active account a wallet disconnect. Endpoint changes apply after MCP server restart.
+For local settings, local records or connection-service recovery, call `settings.create_local_settings_session` to open the internal Settings card. Its name is unchanged; no external URL is returned. Explain Address for viewing assets, Local records, Troubleshooting or Advanced settings as needed and leave selection/confirmation to the user.
+
+For a backup, use the exact label Download backup in Local records. It prepares
+and verifies the snapshot internally and asks the app to save it in one user
+action. Do not instruct a separate Create backup step or confuse Download backup
+with Restore local records. If the actual download function is unsupported,
+the same file is saved once in the Sui MCP backup folder. Use the verified
+Backup saved result's Folder and File name for that local artifact. Do not
+describe that folder as the Host download destination. Suggested file name and Host acknowledgment do not establish where
+or whether a file was saved. Retry download is explicit and may create another
+copy after an unconfirmed earlier request. It uses the same snapshot only during
+its fixed transfer period; a new request after expiry or server restart captures
+current records. Cancel download does not delete a file already saved by the app.
+Use the same function-based product instructions across desktop apps. Missing
+advertisement is not proof of non-support, and timeout, cancellation or denial
+does not trigger local saving. Save a local copy is the explicit decision after
+an earlier possibly handled request. Retry save follows only a confirmed failure
+with no published file; Check status settles uncertain saving or cleanup without
+another file effect. Report saved-file and cleanup facts separately.
+
+Ordinary MCP tools never apply a Settings change. Do not call `ui.act_card` or `ui.read_settings_file` as model work. Never request/paste raw backup bytes or card permissions in chat. Clear default address only changes read context, not wallet connections or admitted transactions. Endpoint changes require quitting/reopening all apps; a connection-service restart does not apply them. Report operation result, temporary-file cleanup and Host download acknowledgment as separate facts. A saved result is not proof that the Host saved a downloaded file. For restore validation refusal, let the user correct input or choose another file and prepare a new confirmation; reading or returning to a frame never applies it.
 
 ## User Vocabulary
 
@@ -518,7 +552,3 @@ Avoid unqualified words such as best, recommended, guaranteed, or safe. Prefer:
 ## Language
 
 This reference document stays in English. Reply in the user's language. Translate response patterns as needed, but keep SDK names, tool names, object IDs, package IDs, and token symbols in their original form.
-
-## Golden Scenarios
-
-Detailed expected response classes live in `docs/golden-scenarios/BEHAVIOR_MATRIX.md`. They are documentation for release review, not automated cross-client results.

package/docs/LOCAL_DB_ARCHITECTURE.md

@@ -10,7 +10,7 @@ The process that binds the configured loopback port initializes these local comp
 
 - a local SQLite store;
 - a mainnet guard for the configured Sui gRPC endpoint;
-- the local review HTTP server on `127.0.0.1`;
+- the shared private HTTP transport on `127.0.0.1`;
 - authenticated internal MCP sessions, reached by each client through a stdio forwarder.
 
 The GraphQL endpoint is also mainnet-guarded when it is saved through settings, imported from a local-data backup, or first used by Sui activity tools.
@@ -33,7 +33,7 @@ User-requested bounded transaction scans can store normalized facts only when a
 
 The default Sui mainnet gRPC and GraphQL endpoints are stored in the local SQLite settings table on first run.
 
-To inspect settings or change local data, ask your AI client to create a Sui MCP local settings session and open the returned settings URL in the same machine's system browser.
+To inspect settings or change local data, ask for the internal Settings card. Ordinary MCP creates an unsubmitted card or reads settings; scoped app-only preparation/confirmation owns changes. No external page or Settings HTTP API remains.
 
 Endpoint changes apply after the MCP server restarts.
 
@@ -105,7 +105,10 @@ The following live session tables hold runtime session state in the shared datab
 - `live_private_review_artifacts`: per-session private review evidence (the transaction-material handle, its digest commitment, and derived evidence), cascade-deleted with its review session.
 - `live_transaction_materials`: locally built unsigned transaction bytes stored as a BLOB behind a redacted handle, with a TTL; retained for the admitted request. Terminal request cleanup removes only material still owned by that revision, preserving newer preparation. Owner replacement deletes old private material while retaining immutable review and chain-result evidence.
 - `live_wallet_connections`: verified connection facts, private topic and callback state.
-- `live_settings_sessions`: short-lived Settings page authority.
+- `live_read_cards`: public card state with private permission hash, scope, operation and CAS revision.
+- `settings_operations`: one draft/upload/preparation/admission/result identity per Settings card, with owner/data epoch, user-data revision, fingerprint and SDK supersession/checkpoint facts. A download stores its typed snapshot lifetime and per-attempt delivery reports in private `preparation_json`, separately from the immutable result. Updating delivery never reserializes a terminal `result_json`.
+- `settings_files`: private file identity, original operation, upload/export role, generated paths, lengths/hash, chunk reservation and seal/invalidation/cleanup state. `cleanup_operation_id` separately names the operation responsible for cleanup; replacement can transfer that responsibility without changing the file identity, public path or input eligibility.
+- `settings_control`: current data epoch/user-data revision, one final-operation slot, one file-I/O reservation and the SDK input block owner. These are semantic state/authority facts, not release-version counters.
 
 These live tables are distinct from the append-only review evidence tables above: the evidence tables remain the durable activity/audit record, while the live tables hold the in-flight session state that the review server serves.
 
@@ -132,13 +135,92 @@ update triggers reject revision-unaware writers: inserts must use
 `revision = 0` and the current write-contract marker, and updates must increase
 the revision by exactly one and keep the current write-contract marker.
 
-Logical local data reset is the local settings page action that clears stored product state through the runtime without requiring manual database-file deletion. Replace-only import is the settings page import path that replaces local product state from a validated backup. When no unsettled financial request prevents replacement, both logical local data reset and replace-only import clear `coin_metadata_cache`, card records, live review/wallet/settings sessions, private review artifacts and transaction material in the same SQLite transaction. A rollback preserves the existing data and permissions. No separate HTTP cleanup call owns permission invalidation. Clearing active account context does not clear it because coin metadata is account-independent.
-
-Non-terminal review session expiry is recorded lazily when the session is read or mutated after its TTL. There is no background expiry worker.
+Reset/import are explicitly confirmed Settings operations. They validate the
+current backup shape and imported mainnet endpoints, check current prepared
+impact and reject unsettled wallet/transaction work. One SQLite transaction
+replaces user data, clears coin metadata and other live authorities, advances
+data epoch and preserves the applying operation's read-only card/result. It
+never recreates that result from a callback after deleting it. Rollback
+preserves the prior data, permissions and admission state.
+The private `live_wallet_connections` service journal remains because replacing
+user data does not end SDK sessions. It cannot restore old card permissions or
+transaction authority and is not imported from a backup. Reset clears the
+default address; an imported default still needs its exact current connection
+ID and approved address. Outstanding connection SDK callbacks also block replacement.
+
+User-data and wallet/request writers invalidate affected preparations and
+increment their card revision in the same transaction. The trigger and `settings_back`
+reuse one SQL transition: a complete, sealed, non-invalidated upload belonging
+to that operation returns to sealed; other preparations return to draft. Old
+confirmations cannot apply. Backup checking and final I/O still verify physical content;
+a manifest alone is not proof of a valid file.
+
+A `download_backup` admission consumes one card input and captures one local-data
+snapshot in the same SQLite transaction. The export role and exact generated
+`.settings-staging/<fileId>.download` namespace identify its private file; an
+export role or display name alone is insufficient. File bytes are not stored
+in operation JSON or nested in exported local data. Physical write, fsync, length and SHA checks
+finish before the snapshot becomes available. `result` is immutable preparation
+evidence; delivery reports have separate typed state and atomic attempt identity.
+
+An exact unsupported download report can atomically reserve final/file I/O and
+admit local publication of that same snapshot. An earlier possibly handled
+attempt instead records a pending local-copy decision. Explicit consent/retry
+uses a distinct save-attempt identity and compare-and-set predecessor, without
+creating another snapshot. Application names and absent capability advertisement
+do not authorize this effect.
+
+The private `download.localSave` journal in `preparation_json` records its source
+manifest, fixed `backups/<operationId>.json` destination, attempt/consent and
+physical source device/inode as decimal strings. The verified source identity
+is committed before exclusive same-volume hard-link publication. The source and
+target must name the recorded file and pass size/SHA checks before `saved` is
+committed. Existing destinations are never overwritten or removed. Private
+unlink follows that result and actual descriptor closure; the final file has
+no automatic expiry. Historical export path validation remains distinct from
+the private `.download` row identity.
+
+Unknown file effects remain `saving`, retaining their source and reservations.
+A failed DB result write retains the ended physical outcome for settlement.
+A missing target is distinct from one that could not be read. Only a verified
+absent target with a valid source permits an explicit retry within the original
+period. Recovery after owner exit verifies an existing source-bound target only;
+an absent or mismatching artifact is not regenerated. The new owner inherits
+settlement responsibility without restoring the old card's action permission.
+A committed saved result remains a past fact when its private file is gone.
+
+The fixed thirty-minute transfer period begins at physical readiness, independently
+of the original input expiry. The owner schedules its earliest live transfer
+deadline; current DB time, owner and epoch decide expiry. An abandoned frame does
+not own cleanup. A failed already-due journal cannot create a zero-delay loop or
+cancel another snapshot's future deadline. Status reads and owner recovery can
+retry cleanup. Current-generation access rejects stale callbacks after replacement.
+
+Private staging files survive as cleanup journal entries when cards are
+invalidated. Reset/import invalidate uploads and private downloads and transfer
+cleanup ownership without changing file identity. Existing public backup files
+remain unchanged. Acknowledgment, explicit cancellation, expiry, source failure
+or owner restart ends private retention, except that an already-admitted local
+publication retains the evidence needed to settle its result first. Its final
+reservation blocks competing Settings application and data replacement until
+physical I/O and result settlement end. Active descriptor reads/writes finish
+before deletion; new ranges and retries are refused once authority ends.
+`temporaryFileCleanup` includes physical cleanup and settlement of the operation's
+ended I/O reservation. Stored results remain readable during pending cleanup,
+including when expiry persistence fails; input remains closed and the failed
+cleanup stays visible. Another operation's reservation is never released.
+
+An explicit same-result read may finish its cleanup or verify an existing
+published export, never regenerate a backup, repeat Host delivery, reapply data
+or replace an SDK run. Files/permissions/SDK credentials/private transaction
+material are excluded from public backups. Clearing the default address does
+not invalidate account-independent coin metadata or disconnect the wallet.
+
+Non-terminal review session expiry is recorded lazily when the session is read or mutated after its TTL. Review-session expiry has no background worker; private download retention uses the separate owner timer described above.
 
 ## Shared local server
 
-Exactly one parent runtime owner per data directory binds the configured loopback port and creates the shared product services and SQLite stores. Other clients authenticate the listener before sending control credentials and forward MCP messages to it. The authentication covers database identity, internal API version 7, configuration (including WalletConnect project configuration) and server instance. Proof and subsequent dispatch use the same TCP connection. Host/Origin validation is separate from authentication; neither protects against a malicious process running as the same OS user.
+Exactly one parent runtime owner per data directory binds the configured loopback port and creates the shared product services and SQLite stores. Other clients authenticate the listener before sending control credentials and forward MCP messages to it. The authentication covers database identity, the package release version, configuration (including WalletConnect project configuration) and server instance. Proof and subsequent dispatch use the same TCP connection. Host/Origin validation is separate from authentication; neither protects against a malicious process running as the same OS user.
 
 The private `runtime-control.key` file is separate from UI permissions and wallet credentials and is excluded from product backups. Stdio closure and process signals close the owned server. No client signals a peer backend. The parent may terminate only its own SDK child. A peer can acquire the port after it becomes free. Failed calls are not replayed automatically. MCP framing, cancellation and EOF handling start before backend acquisition; wallet SDK readiness does not block parent service startup.
 
@@ -204,10 +286,12 @@ child exit, while parent verification, submission and lookup flags remain until
 their own work ends. SDK readiness does not clear those independent guards.
 
 Initial SDK restoration considers the entire known connection set, including
-prior-owner records, before publishing current eligibility. Only confirmed
-known connected records transfer to the new owner. Multiple valid records are
-management targets, not usable wallet choices: `connectionConflict` is derived
-from those rows with no additional table. Targeted disconnection remains
+prior-owner records, before publishing current eligibility. Confirmed known
+connected records transfer to the new owner. Known terminal records with a
+present SDK session transfer management metadata without changing their outcome.
+Multiple known occupied connections are management targets, not usable wallet
+choices: `connectionConflict` is derived from the journal and current supervisor
+snapshot, with no additional table. Targeted disconnection remains
 available while new pairing, account use, review preparation and signing are
 blocked. The final submission transaction applies the same single-connection
 rule. Failed/stopped records and unknown SDK sessions do not restore authority.
@@ -221,6 +305,17 @@ database evaluation time and published to cards as `usableConnectionId` and
 `assetReadAccount`; Views do not recount recorded connections. This adds no
 table or expiry writer. Stored status, disconnection outcomes and historical
 account records retain their separate meanings.
+The store reads the current run's private supervisor snapshot inside evaluation
+and immediate admission. Missing inspection does not mean an empty service.
+`manageableConnectionIds` names exact nonpending recorded disconnect targets,
+including known terminal records whose SDK sessions remain present. They are not
+usable account choices. `connectionReconciliationRequired: true` means a present
+SDK session has no journal target after ordinary registration/cleanup has ended;
+it blocks pairing, account use and unsubmitted signing until the user removes the
+retained connection in the wallet app and a complete current-run observation
+confirms absence. Settings can explicitly restart the service to inspect it
+again; restart alone does not resolve retained presence. Topics remain private. A pending registration
+is not reported as a reconciliation failure.
 
 An admission that changes connection eligibility or targets also publishes the
 owner's ready Connect/Review card revisions in that same transaction, after
@@ -234,7 +329,8 @@ write; they do not start another SDK process. Repeated reads after a successful
 repair do not repeat the transition. Unrelated stored transaction results and
 already dispatched chain observation remain independent of that write.
 The supervisor's explicit replacement primitive requires fencing and actual
-child exit before a new run, but it has no current card or model entry point.
+child exit before a new run. Its user entry point is a scoped, explicitly
+prepared and confirmed Settings card; ordinary model calls cannot replace it.
 
 If a completed callback's flag write fails, the owner retains its exact operation
 identity as completion evidence. A current state read can retry that database
@@ -257,6 +353,25 @@ The target session/card's own required expiry writes still propagate errors.
 This is not availability during an unreadable database or a bypass of authority
 revocation failures.
 
+Connection facts and workflow maintenance have separate internal contracts.
+`readConnectionFacts(at)` collects recorded connections, current-run SDK presence,
+pending work and read-address provenance from one SQLite read snapshot. The
+shared selector and qualification projection compute eligibility from those
+facts; they do not update requests, expire connections or repair callbacks.
+Settings general facts use this diagnostic path and stored counts, so another
+request's refused deadline write does not prevent opening or reading Settings.
+Creating a card and checking its own permission, input expiry or cleanup retain
+their own writes. Stored counts are not a promise about a later deletion impact.
+
+`reconcileAndEvaluate` requires a current-wallet or server-bound review purpose.
+Current wallet consumers use `reconcileConnectionContext`; exact request reads
+retain their narrower target. Reset/import preparation and final admission still
+settle deadlines and compare the current impact in their transaction. Snapshot
+memory may precede its DB publication: initializing/state_sync does not grant
+account use or establish an unrecorded-connection removal diagnosis. Only a
+published available run can qualify that guidance; missing guidance does not
+prove that the SDK is empty.
+
 Successful reset/import invalidates pending SDK startup or recovery in the old
 data generation and ends that child without automatically starting another.
 Rejected or rolled-back replacement does not change the run or generation.
@@ -335,13 +450,21 @@ unknown-outcome records may be removed after the explicit warning; removing
 records cannot cancel a transaction. A generation change rejects late writes.
 
 The wallet store advances expired signature and initial-observation deadlines
-through the same request transition writer used by the workflow. Current
-session/card reads, current local-data counts and preview counts, and the actual
-reset/import transaction use this operation even when no View is open. Expiry
+through the same request transition writer used by the workflow. Explicit
+current-wallet reconciliation settles current wallet work. A server-bound review
+read settles its own request target unless it depends on current wallet work;
+it does not use an unrelated completed request as a reason for global maintenance.
+Reset/import preparation settles deadlines before calculating its impact, and
+final admission settles them again and compares the current impact in the same
+transaction as replacement, even when no View is open.
+
+General Settings facts and stored local-data counts use the diagnostic read
+contract; they do not advance live requests. Creating or reading a card still
+checks that card's own permission, input expiry and operation cleanup. Expiry
 does not clear pending SDK/submission/lookup callbacks. Stored activity queries
-and public backup export only read recorded facts; they do not advance live
-requests or interpret imported history as authority. Replacement warnings do not
-claim an earlier counts snapshot is the number being deleted now.
+and public backup export also read recorded facts without advancing live
+requests or treating imported history as authority. Replacement warnings do not
+claim an earlier stored-counts snapshot is the number being deleted now.
 
 Disconnect progress is the existing running Connect card's accepted disconnect
 action and connection reference. Connection updates preserve that operation
@@ -349,11 +472,11 @@ until its result is recorded; no additional persisted connection status is used.
 
 ### Current format and backups
 
-The current `user_version` is 9. It identifies one supported schema; there is no migration registry or older-format decoder. All clients sharing a data directory must use the same compatible runtime.
+The runtime accepts one current SQLite structure, checked against its table, column, constraint, index and trigger definitions before writes. There is no separate database version counter, migration registry or older-format decoder. All clients sharing a data directory must use the same package release.
 
-A current backup carries `format`, `schemaVersion`, `network`, `exportedAt` and its product data. Import rejects a missing or different schema identifier, incomplete required fields, invalid references or invalid raw quantities. Missing settings or activity arrays are not filled from defaults. Supported `function_scan` provenance remains part of the current format. Validation failure leaves current data intact.
+A current backup carries `format`, `network`, `exportedAt` and its product data. It has no numeric schema version. Import rejects a different format, unknown or missing fields, invalid references or invalid raw quantities. Missing settings or activity arrays are not filled from defaults. Supported `function_scan` provenance remains part of the current format. Validation failure leaves current data intact.
 
-New installations do not inherit older local review records, activity scans, known/active accounts or stored endpoints. Users configure the required context again; environment overrides retain their existing precedence. Empty local history does not imply an absence of on-chain transactions. Existing DB and backup files are not deleted by startup.
+With a new empty data directory, users configure account context and endpoints; environment overrides retain their existing precedence. Empty local history does not imply an absence of on-chain transactions. Existing DB and backup files are not deleted by startup.
 
 ## Boundaries
 
@@ -373,7 +496,7 @@ Ownership and simulation private artifacts use their v2 evidence formats to
 bind transaction funding to the stored material. They cover real coin objects,
 address withdrawals, gas reservations, and their observed balance/epoch facts.
 They are deeply copied and revalidated before admission, and are excluded from
-public backup. They introduce no table, column, or DB format migration.
+public backup.
 
 Old private evidence is not upgraded into funding proof. Existing owner recovery
 removes private material; a new review recomputes it. Historical public reviews,