@fased/fased 0.1.67 → 0.1.69

package/dist/gateway/server-http.js

@@ -11,6 +11,7 @@ import { resolveLocalSignerSocketPath, resolveWalletRuntimeConfig } from "../wal
 import { WALLET_PROVIDER_IDS, checkNamedWalletDeletionSafety, deleteNamedWallet, normalizeWalletUserRole, readWalletProviderRegistry, resolveWalletSelection, resolveWalletUserRole, setAgentWalletAssignment, setDefaultWallet, setNamedWalletRole, setWalletProviderEnabled, upsertNamedWallet } from "../wallet/wallet-provider-registry.js";
 import { resolveAgentPublicOrigin, resolveFederationBaseUrl, resolveFederationBondWalletId, resolveFederationHandle } from "../federation/runtime.js";
 import { isValidSolanaAddress } from "../wallet/solana-address.js";
+import { fetchPinnedSolanaRpcRead } from "../wallet/solana-rpc-read-fetch.js";
 import { fetchSolanaMintInfoViaRpc, fetchSolanaNativeBalanceViaRpc, fetchSolanaTokenBalanceViaRpc, fetchSolanaWalletAssetsViaRpc, invalidateSolanaAssetRpcCaches, summarizeSolanaAssetRpcMetrics } from "../wallet/solana-assets.js";
 import { tryResolveSatRuntimeIds } from "../config/sat-runtime-ids.js";
 import { commitWalletPolicyConfigUpdate, prepareWalletPolicyConfigUpdate, resolveWalletPolicyConfig, resolveWalletRecurringTransferPolicy } from "../wallet/wallet-policy.js";
@@ -28,19 +29,22 @@ import { normalizeCanvasScopedUrl } from "./canvas-capability.js";
 import { A2UI_PATH, CANVAS_HOST_PATH, CANVAS_WS_PATH, handleA2uiHttpRequest } from "../canvas-host/a2ui.js";
 import { resolveFederationBondWallet } from "../wallet/solana-bond-signing.js";
 import { createAndSubmitFederationBondProof, loadPersistedFederationBondProof, submitFederationBondProof } from "../federation/auto-connect.js";
+import { resolveNativeSignerWalletId } from "../wallet/native-signer-wallet-id.js";
 import { beginWalletApprovalAssertion, beginWalletPasskeyRegistration, consumeWalletApprovalGrant, createWalletApprovalChallenge, finishWalletApprovalAssertion, finishWalletPasskeyRegistration, listWalletPasskeys, readWalletApprovalAuthSnapshot, removeWalletPasskey, resolveWalletApprovalAuthMode, resolveWalletApprovalChallengeTtlSeconds, resolveWalletApprovalGrantTtlSeconds } from "../wallet/wallet-approval-auth.js";
 import { readWalletStatusSnapshot } from "../wallet/wallet-status.js";
 import { inspectSatBondPosition, inspectSatBondStakingDistributor, inspectSatBondStakingPosition, inspectSatChainSlot, invalidateSatReadCaches } from "../extensions/sat-mining/src/rpc-read.js";
 import { digestSatSubmissionIntent } from "../extensions/sat-mining/src/submission-ledger.js";
 import { runWithSatSubmissionWorkflow, submitSatCancelBondUnlock, submitSatClaimBondStakingRewards, submitSatFinalizeBondUnlock, submitSatIncreaseBondPosition, submitSatOpenBondPosition, submitSatRequestBondUnlock, submitSatSyncBondStakingPosition, submitSatSyncBondStakingRewards } from "../extensions/sat-mining/src/solana-submit.js";
 import { resolveAgentAvatar } from "../agents/identity-avatar.js";
-import { resolveNativeSignerWalletId } from "../wallet/native-signer-wallet-id.js";
+import { configureSignerOwnedWalletNetwork } from "../wallet/signer-network-admin.js";
 import { listWalletInboundEvents, pollWalletInboundEvents, reconcileWalletInboundEvents, recordWalletInboundWebhookEvent } from "../wallet/wallet-inbound-events.js";
 import { walletSetupCommand } from "../commands/wallet.js";
 import { getDiagnosticStabilitySnapshot } from "../logging/diagnostic-stability.js";
 import { resolveManagedFederationPublicUrl } from "../managed/federation.js";
+import { lockSignerOwnedWalletForArchive } from "../wallet/local-socket-signer-archive.js";
 import { LocalSignerPolicyAdminRequiredError, buildLocalSignerPolicyTightening, localSignerPolicyState } from "../wallet/local-socket-signer-policy.js";
 import { executeWalletStandardReview, prepareWalletStandardReview, readWalletStandardReviewTxHash } from "../wallet/wallet-standard-review.js";
+import { renderQrPngBase64 } from "../web/qr-image.js";
 import { createA2aHandler } from "./a2a-http.js";
 import { CONTROL_UI_BOOT_CHECK_PATH, resolveControlUiBootCheck } from "./control-ui-boot-check.js";
 import { normalizePublicHost, resolveControlUiPublicHost } from "./control-ui-login.js";
@@ -100,12 +104,19 @@ function parseCookies(raw) {
 	}
 	return cookies;
 }
-function isLocalHostName(host) {
+function normalizeHostName(host) {
 	const raw = host.trim().toLowerCase();
-	const normalized = raw.startsWith("[") ? (() => {
+	return raw.startsWith("[") ? (() => {
 		const end = raw.indexOf("]");
 		return end > 0 ? raw.slice(1, end) : raw;
 	})() : raw.replace(/:\d+$/, "");
+}
+function isLiteralLoopbackHostName(host) {
+	const normalized = normalizeHostName(host);
+	return normalized === "localhost" || normalized === "127.0.0.1" || normalized === "::1";
+}
+function isLocalHostName(host) {
+	const normalized = normalizeHostName(host);
 	return normalized === "localhost" || normalized === "127.0.0.1" || normalized === "::1" || normalized.endsWith(".local");
 }
 function isLoopbackBrowserOrigin(origin) {
@@ -114,7 +125,18 @@ function isLoopbackBrowserOrigin(origin) {
 		if (parsed.protocol !== "http:" && parsed.protocol !== "https:") {
 			return false;
 		}
-		return isLocalHostName(parsed.host);
+		return isLiteralLoopbackHostName(parsed.host);
+	} catch {
+		return false;
+	}
+}
+function isSameBrowserOriginHost(origin, host) {
+	try {
+		const parsed = new URL(origin);
+		if (parsed.protocol !== "http:" && parsed.protocol !== "https:") {
+			return false;
+		}
+		return parsed.host.toLowerCase() === host.trim().toLowerCase();
 	} catch {
 		return false;
 	}
@@ -132,7 +154,7 @@ function applyLoopbackCorsIfAllowed(req, res, host) {
 	if (!origin) {
 		return false;
 	}
-	if (!isLocalHostName(host) || !isLoopbackBrowserOrigin(origin)) {
+	if (!isLocalHostName(host) || !isLoopbackBrowserOrigin(origin) && !isSameBrowserOriginHost(origin, host)) {
 		return false;
 	}
 	res.setHeader("Access-Control-Allow-Origin", origin);
@@ -659,7 +681,7 @@ async function readWalletSettingsSignerPolicy(params) {
 				...asset,
 				destinations: [...asset.destinations]
 			})),
-			...state === "locked" ? { guidance: "Signer policy is deny-all. Install an owner-reviewed policy through the native signer control socket; the Gateway can only tighten it." } : {}
+			...state === "locked" ? { guidance: `This existing wallet is deny-all. Review its immutable role, then run: fased wallet policy activate-role-baseline --wallet-id ${walletId} --role ${policy.role} --confirm` } : {}
 		};
 	} catch {
 		return {
@@ -935,20 +957,20 @@ async function fetchSolanaLamportsViaRpc(params) {
 	if (!rpcUrl || !address) {
 		return null;
 	}
-	const controller = new AbortController();
-	const timeout = setTimeout(() => controller.abort(), Math.max(250, params.timeoutMs));
+	let release;
 	try {
-		const response = await fetch(rpcUrl, {
-			method: "POST",
-			headers: { "content-type": "application/json" },
+		const guarded = await fetchPinnedSolanaRpcRead({
+			rpcUrl,
+			timeoutMs: params.timeoutMs,
 			body: JSON.stringify({
 				jsonrpc: "2.0",
 				id: "wallet-balance-fallback",
 				method: "getBalance",
 				params: [address]
-			}),
-			signal: controller.signal
+			})
 		});
+		release = guarded.release;
+		const response = guarded.response;
 		if (!response.ok) {
 			recordWalletGatewayRpcMethod("direct.getBalance", "failure");
 			return null;
@@ -962,7 +984,7 @@ async function fetchSolanaLamportsViaRpc(params) {
 		recordWalletGatewayRpcMethod("direct.getBalance", "failure");
 		return null;
 	} finally {
-		clearTimeout(timeout);
+		await release?.();
 	}
 }
 function resolveWalletProbeTimeoutMs(env) {
@@ -1004,11 +1026,18 @@ function resolveMiningAgentWalletConflict(walletId) {
 		return null;
 	}
 	const activeMiningWalletId = readSatMiningWalletIdFromConfig(loadConfig());
-	if (activeMiningWalletId === normalizedWalletId) {
-		return null;
+	if (activeMiningWalletId && activeMiningWalletId !== normalizedWalletId) {
+		return `SAT Mining already uses ${activeMiningWalletId}. Archive that singleton wallet before attaching a replacement.`;
 	}
 	const registry = readWalletProviderRegistry(process.env);
 	const wallet = registry.wallets.find((entry) => entry.id === normalizedWalletId);
+	const otherMiningWallet = registry.wallets.find((entry) => entry.id !== normalizedWalletId && resolveWalletUserRole(entry) === "mining");
+	if (otherMiningWallet) {
+		return `SAT Mining already has the singleton wallet ${otherMiningWallet.id}. Archive it before attaching a replacement.`;
+	}
+	if (!wallet) {
+		return "SAT Mining requires an existing dedicated Mining wallet.";
+	}
 	const purpose = resolveWalletUserRole(wallet);
 	if (normalizedWalletId === registry.defaultWalletId || purpose === "agent") {
 		return "SAT Mining must use a dedicated Mining wallet. Create a new Mining wallet instead of reusing an Agent wallet.";
@@ -1288,9 +1317,9 @@ async function checkSolanaAtaReadiness(address, env) {
 	}
 	try {
 		const USDC_MINT = "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v";
-		const response = await fetch(rpcUrl, {
-			method: "POST",
-			headers: { "Content-Type": "application/json" },
+		const guarded = await fetchPinnedSolanaRpcRead({
+			rpcUrl,
+			timeoutMs: 1e4,
 			body: JSON.stringify({
 				jsonrpc: "2.0",
 				id: 1,
@@ -1302,15 +1331,19 @@ async function checkSolanaAtaReadiness(address, env) {
 				]
 			})
 		});
-		if (!response.ok) {
-			recordWalletGatewayRpcMethod("direct.getTokenAccountsByOwner", "failure");
-			return false;
+		try {
+			if (!guarded.response.ok) {
+				recordWalletGatewayRpcMethod("direct.getTokenAccountsByOwner", "failure");
+				return false;
+			}
+			const payload = await guarded.response.json();
+			const accounts = payload?.result?.value;
+			const ok = Array.isArray(accounts);
+			recordWalletGatewayRpcMethod("direct.getTokenAccountsByOwner", ok ? "success" : "failure");
+			return ok && accounts.length > 0;
+		} finally {
+			await guarded.release();
 		}
-		const payload = await response.json();
-		const accounts = payload?.result?.value;
-		const ok = Array.isArray(accounts);
-		recordWalletGatewayRpcMethod("direct.getTokenAccountsByOwner", ok ? "success" : "failure");
-		return ok && accounts.length > 0;
 	} catch {
 		recordWalletGatewayRpcMethod("direct.getTokenAccountsByOwner", "failure");
 		return false;
@@ -3065,7 +3098,20 @@ function createGatewayHttpServer(opts) {
 			const directLocalRequest = !tailscaleProxyConfigured && isDirectLoopbackRequest(req, trustedProxies);
 			const ensureWalletApiAuthorized = async () => {
 				if (directLocalRequest) {
-					return true;
+					const requestOrigin = String(getHeader(req, "origin") ?? "").trim();
+					if (!requestOrigin || isLoopbackBrowserOrigin(requestOrigin)) {
+						return true;
+					}
+					if (!loopbackCorsApplied) {
+						sendLoginResponse(403, {
+							ok: false,
+							error: {
+								code: "forbidden_origin",
+								message: "cross-origin browser requests are not allowed on the loopback wallet API"
+							}
+						});
+						return false;
+					}
 				}
 				let authorized = false;
 				const bearer = getBearerToken(req);
@@ -4476,24 +4522,24 @@ function createGatewayHttpServer(opts) {
 					const requestedWalletId = typeof payload.walletId === "string" ? payload.walletId.trim() : "";
 					const roleProvided = Object.prototype.hasOwnProperty.call(payload, "role");
 					const normalizedRole = roleProvided ? normalizeWalletUserRole(payload.role) : undefined;
-					const requestedRole = normalizedRole === "agent" || normalizedRole === "vault" ? normalizedRole : undefined;
+					const requestedRole = normalizedRole === "agent" || normalizedRole === "mining" || normalizedRole === "vault" ? normalizedRole : undefined;
 					if (roleProvided && !requestedRole) {
 						sendLoginResponse(400, {
 							ok: false,
 							error: {
 								code: "invalid_wallet_role",
-								message: "role must be agent or vault"
+								message: "role must be agent, mining, or vault"
 							}
 						});
 						return;
 					}
 					const activeMiningWalletId = readSatMiningWalletIdFromConfig(loadConfig());
-					if (requestedRole && requestedWalletId && requestedWalletId === activeMiningWalletId) {
+					if (requestedRole === "mining" && activeMiningWalletId && requestedWalletId !== activeMiningWalletId) {
 						sendLoginResponse(409, {
 							ok: false,
 							error: {
 								code: "wallet_in_use",
-								message: "walletId is the singleton SAT mining wallet; delete and recreate @wallet:mining before changing this wallet role"
+								message: `Mining already uses the singleton wallet ${activeMiningWalletId}; use the reviewed Replace/Archive flow instead of creating a second Mining wallet`
 							}
 						});
 						return;
@@ -4581,6 +4627,16 @@ function createGatewayHttpServer(opts) {
 							});
 							return;
 						}
+						if (!requestedRole) {
+							sendLoginResponse(400, {
+								ok: false,
+								error: {
+									code: "invalid_wallet_role",
+									message: "choose agent, mining, or vault; the native signer never infers a role"
+								}
+							});
+							return;
+						}
 						const chain = inferLocalSignerCreateChain({
 							payloadChain: payload.chain,
 							walletId: requestedWalletId,
@@ -4597,18 +4653,26 @@ function createGatewayHttpServer(opts) {
 							});
 							return;
 						}
+						const rpcUrl = typeof payload.rpcUrl === "string" ? payload.rpcUrl.trim() : "";
+						if (!rpcUrl) {
+							sendLoginResponse(400, {
+								ok: false,
+								error: {
+									code: "invalid_request",
+									message: "one primary Solana RPC URL is required for native signer wallet creation"
+								}
+							});
+							return;
+						}
 						try {
-							const effectiveEnv = {
-								...process.env,
-								...cfg.env?.vars
-							};
 							await walletSetupCommand(silentWalletSetupRuntime, {
 								mode: "local-signer-create",
 								chain,
 								walletId: requestedWalletId,
 								walletName,
-								rpcUrl: resolveWalletRpcUrlFromEnv(effectiveEnv, chain, requestedWalletId),
+								rpcUrl,
 								role: requestedRole,
+								force: true,
 								nonInteractive: true,
 								noSignerHints: true,
 								noDoctor: true
@@ -4738,13 +4802,15 @@ function createGatewayHttpServer(opts) {
 					const name = typeof payload.name === "string" && payload.name.trim() ? payload.name.trim() : undefined;
 					const roleProvided = Object.prototype.hasOwnProperty.call(payload, "role");
 					const normalizedRole = roleProvided ? normalizeWalletUserRole(payload.role) : undefined;
-					const requestedRole = normalizedRole === "agent" || normalizedRole === "vault" ? normalizedRole : undefined;
-					if (!walletId || !name && !roleProvided) {
+					const requestedRole = normalizedRole === "agent" || normalizedRole === "mining" || normalizedRole === "vault" ? normalizedRole : undefined;
+					const rpcUrl = typeof payload.rpcUrl === "string" ? payload.rpcUrl.trim() : "";
+					const rpcProvided = Object.prototype.hasOwnProperty.call(payload, "rpcUrl");
+					if (!walletId || !name && !roleProvided && !rpcProvided) {
 						sendLoginResponse(400, {
 							ok: false,
 							error: {
 								code: "invalid_request",
-								message: "walletId and name or role are required"
+								message: "walletId and role or rpcUrl are required"
 							}
 						});
 						return;
@@ -4754,7 +4820,7 @@ function createGatewayHttpServer(opts) {
 							ok: false,
 							error: {
 								code: "invalid_wallet_role",
-								message: "role must be agent or vault"
+								message: "role must be agent, mining, or vault"
 							}
 						});
 						return;
@@ -4781,13 +4847,117 @@ function createGatewayHttpServer(opts) {
 						});
 						return;
 					}
+					if (rpcProvided) {
+						if (!rpcUrl) {
+							sendLoginResponse(400, {
+								ok: false,
+								error: {
+									code: "invalid_request",
+									message: "rpcUrl must be a non-empty primary Solana RPC URL"
+								}
+							});
+							return;
+						}
+						if (existing.providerId !== "local-socket-signer") {
+							sendLoginResponse(409, {
+								ok: false,
+								error: {
+									code: "invalid_provider",
+									message: "primary RPC editing is available only for native signer wallets"
+								}
+							});
+							return;
+						}
+						const cfg = loadConfig();
+						if (!ensureWalletApprovalAuthorized({
+							operation: "wallet.network",
+							cfg
+						})) {
+							return;
+						}
+						try {
+							const effectiveEnv = {
+								...process.env,
+								...cfg.env?.vars
+							};
+							const signerWalletId = resolveNativeSignerWalletId(existing);
+							const network = await configureSignerOwnedWalletNetwork({
+								walletId: signerWalletId,
+								primaryRpcUrl: rpcUrl,
+								env: effectiveEnv,
+								socketPath: resolveLocalSignerSocketPath(effectiveEnv)
+							});
+							const suffix = normalizeWalletIdForEnvSuffix(walletId)?.toUpperCase();
+							const rpcKey = suffix ? `FASED_WALLET_SOLANA_RPC_URL__${suffix}` : "FASED_WALLET_SOLANA_RPC_URL";
+							const configUpdate = await updateWalletConfig({
+								env: effectiveEnv,
+								mutate: (next) => {
+									next.env = {
+										...next.env,
+										vars: {
+											...next.env?.vars,
+											[rpcKey]: rpcUrl
+										}
+									};
+								}
+							});
+							if (!configUpdate.ok) {
+								throw new Error(`signer accepted network version ${network.version}, but app configuration persistence failed: ${configUpdate.message}`);
+							}
+							upsertNamedWallet({
+								walletId: existing.id,
+								name: existing.name,
+								providerId: existing.providerId,
+								addresses: existing.addresses,
+								metadata: {
+									...existing.metadata,
+									networkHash: network.hash,
+									networkVersion: network.version,
+									networkReady: network.ready
+								},
+								env: process.env
+							});
+							appendWalletAuditEntry({
+								action: "wallet_rpc_updated",
+								actor: "control-ui",
+								details: {
+									walletId,
+									networkVersion: network.version,
+									networkReady: network.ready
+								},
+								env: process.env
+							});
+						} catch (err) {
+							sendLoginResponse(502, {
+								ok: false,
+								error: {
+									code: "wallet_rpc_update_failed",
+									message: err instanceof Error ? err.message : String(err)
+								}
+							});
+							return;
+						}
+					}
 					const activeMiningWalletId = readSatMiningWalletIdFromConfig(loadConfig());
-					if (requestedRole && walletId === activeMiningWalletId) {
+					if (requestedRole === "mining") {
+						const miningConflict = resolveMiningAgentWalletConflict(walletId);
+						if (miningConflict) {
+							sendLoginResponse(409, {
+								ok: false,
+								error: {
+									code: "wallet_in_use",
+									message: miningConflict
+								}
+							});
+							return;
+						}
+					}
+					if (requestedRole && requestedRole !== "mining" && walletId === activeMiningWalletId) {
 						sendLoginResponse(409, {
 							ok: false,
 							error: {
 								code: "wallet_in_use",
-								message: "walletId is the singleton SAT mining wallet; delete and recreate @wallet:mining before changing this wallet role"
+								message: "walletId is the singleton SAT Mining wallet; use the guarded Archive/Replace flow before creating a wallet with a different role"
 							}
 						});
 						return;
@@ -4806,7 +4976,7 @@ function createGatewayHttpServer(opts) {
 										ok: false,
 										error: {
 											code: "signer_wallet_role_immutable",
-											message: `The native signer owns this wallet as role=${signerPolicy.role}; the Gateway cannot change it to ${requestedRole}. ` + "Create a new signer-owned wallet with the required locked role through Local onboarding or an authenticated Hosting administrator session."
+											message: `The native signer owns this wallet as role=${signerPolicy.role}; the Gateway cannot change it to ${requestedRole}. ` + "Create a new signer-owned wallet with the required locked role, then use the guarded Archive/Replace flow for the old wallet."
 										}
 									});
 									return;
@@ -4863,6 +5033,8 @@ function createGatewayHttpServer(opts) {
 					}
 					const payload = body.value ?? {};
 					const walletId = typeof payload.walletId === "string" ? payload.walletId.trim() : "";
+					const archiveRequested = payload.archive === true;
+					const archiveConfirmation = typeof payload.confirmWalletId === "string" ? payload.confirmWalletId.trim() : "";
 					if (!walletId) {
 						sendLoginResponse(400, {
 							ok: false,
@@ -4873,13 +5045,23 @@ function createGatewayHttpServer(opts) {
 						});
 						return;
 					}
+					if (archiveRequested && archiveConfirmation !== walletId) {
+						sendLoginResponse(400, {
+							ok: false,
+							error: {
+								code: "archive_confirmation_required",
+								message: "confirmWalletId must exactly match walletId"
+							}
+						});
+						return;
+					}
 					const activeMiningWalletId = readSatMiningWalletIdFromConfig(loadConfig());
-					if (activeMiningWalletId === walletId) {
+					if (activeMiningWalletId === walletId && !archiveRequested) {
 						sendLoginResponse(409, {
 							ok: false,
 							error: {
 								code: "wallet_in_use",
-								message: "walletId is the singleton SAT mining wallet; use onboarding or CLI guarded delete for @wallet:mining instead of this API"
+								message: "walletId is the singleton SAT Mining wallet; request the guarded Archive flow instead of ordinary delete"
 							}
 						});
 						return;
@@ -4896,6 +5078,16 @@ function createGatewayHttpServer(opts) {
 						});
 						return;
 					}
+					if (resolveWalletUserRole(existing) === "mining") {
+						sendLoginResponse(409, {
+							ok: false,
+							error: {
+								code: "mining_retirement_required",
+								message: "Mining wallets cannot be deleted directly; use Retire and replace Mining wallet so signer acknowledgement precedes registry detachment"
+							}
+						});
+						return;
+					}
 					const deletionSafety = checkNamedWalletDeletionSafety({
 						walletId,
 						env: process.env
@@ -4911,6 +5103,88 @@ function createGatewayHttpServer(opts) {
 						});
 						return;
 					}
+					if (existing.providerId === "local-socket-signer" && archiveRequested) {
+						const cfg = loadConfig();
+						if (!ensureWalletApprovalAuthorized({
+							operation: "wallet.archive",
+							cfg
+						})) {
+							return;
+						}
+						let archivedPolicy;
+						try {
+							const effectiveEnv = {
+								...process.env,
+								...cfg.env?.vars
+							};
+							archivedPolicy = await lockSignerOwnedWalletForArchive({
+								wallet: existing,
+								socketPath: resolveLocalSignerSocketPath(effectiveEnv)
+							});
+							const federationWalletId = resolveFederationBondDefaultWalletId(cfg);
+							const suffix = normalizeWalletIdForEnvSuffix(walletId)?.toUpperCase();
+							const rpcKey = suffix ? `FASED_WALLET_SOLANA_RPC_URL__${suffix}` : "FASED_WALLET_SOLANA_RPC_URL";
+							const updated = await updateWalletConfig({
+								env: effectiveEnv,
+								mutate: (next) => {
+									if (next.env?.vars) {
+										delete next.env.vars[rpcKey];
+									}
+									const currentEntry = next.plugins?.entries?.["sat-mining"];
+									const currentSatConfig = currentEntry?.config && typeof currentEntry.config === "object" && !Array.isArray(currentEntry.config) ? { ...currentEntry.config } : {};
+									if (currentSatConfig.walletId === walletId) {
+										delete currentSatConfig.walletId;
+										next.plugins = {
+											...next.plugins,
+											entries: {
+												...next.plugins?.entries,
+												"sat-mining": {
+													enabled: true,
+													...currentEntry,
+													config: currentSatConfig
+												}
+											}
+										};
+									}
+									if (federationWalletId === walletId) {
+										applyFederationBondWalletConfig(next, null);
+									}
+								}
+							});
+							if (!updated.ok) {
+								throw new Error(`signer locked the wallet, but attachment cleanup failed: ${updated.message}`);
+							}
+						} catch (err) {
+							sendLoginResponse(502, {
+								ok: false,
+								error: {
+									code: "wallet_archive_failed",
+									message: err instanceof Error ? err.message : String(err)
+								}
+							});
+							return;
+						}
+						const removed = deleteNamedWallet({
+							walletId,
+							env: process.env
+						});
+						appendWalletAuditEntry({
+							action: "wallet_archived",
+							actor: "control-ui",
+							details: {
+								walletId,
+								signerWalletId: archivedPolicy.walletId,
+								denyAllPolicyVersion: archivedPolicy.version
+							},
+							env: process.env
+						});
+						sendLoginResponse(200, {
+							ok: true,
+							removed: removed.removed,
+							archived: true
+						});
+						return;
+					}
 					if (existing.providerId === "local-socket-signer" || existing.providerId === "embedded-keystore" || existing.metadata?.selfHosted === true) {
 						sendLoginResponse(409, {
 							ok: false,
@@ -4943,6 +5217,44 @@ function createGatewayHttpServer(opts) {
 				});
 				return;
 			}
+			if (requestPath === "/api/wallet/receive-qr") {
+				if (!await ensureWalletApiAuthorized()) {
+					return;
+				}
+				if (req.method !== "GET") {
+					res.statusCode = 405;
+					res.setHeader("Allow", "GET");
+					sendLoginResponse(405, {
+						ok: false,
+						error: {
+							code: "method_not_allowed",
+							message: "method must be GET"
+						}
+					});
+					return;
+				}
+				const walletId = parsedUrl.searchParams.get("walletId")?.trim() ?? "";
+				const wallet = readWalletProviderRegistry(process.env).wallets.find((entry) => entry.id === walletId);
+				const address = wallet?.addresses?.solana?.trim() ?? "";
+				if (!walletId || !address || !isValidSolanaAddress(address)) {
+					sendLoginResponse(404, {
+						ok: false,
+						error: {
+							code: "wallet_address_not_found",
+							message: "wallet address not found"
+						}
+					});
+					return;
+				}
+				const png = Buffer.from(await renderQrPngBase64(`solana:${address}`), "base64");
+				res.statusCode = 200;
+				res.setHeader("Content-Type", "image/png");
+				res.setHeader("Content-Length", String(png.byteLength));
+				res.setHeader("Cache-Control", "private, no-store");
+				res.setHeader("X-Content-Type-Options", "nosniff");
+				res.end(png);
+				return;
+			}
 			if (requestPath === "/api/wallet/assignments") {
 				if (!await ensureWalletApiAuthorized()) {
 					return;
@@ -4987,7 +5299,7 @@ function createGatewayHttpServer(opts) {
 								ok: false,
 								error: {
 									code: "wallet_in_use",
-									message: "walletId is the singleton SAT mining wallet; delete and recreate @wallet:mining before making it the primary Agent wallet"
+									message: "walletId is the singleton SAT Mining wallet; Archive/Replace Mining with an Agent wallet before making it the Default Agent wallet fallback"
 								}
 							});
 							return;
@@ -4996,12 +5308,12 @@ function createGatewayHttpServer(opts) {
 							const registry = readWalletProviderRegistry(process.env);
 							const wallet = registry.wallets.find((entry) => entry.id === nextDefaultWalletId);
 							const role = resolveWalletUserRole(wallet) ?? (registry.defaultWalletId === nextDefaultWalletId ? "agent" : undefined);
-							if (role && role !== "agent") {
+							if (role !== "agent") {
 								sendLoginResponse(409, {
 									ok: false,
 									error: {
 										code: "wallet_purpose_locked",
-										message: "only Agent wallets can become the primary Agent fallback; create a new Agent wallet instead"
+										message: "only an explicit Agent wallet can become the Default Agent wallet fallback; create or select an Agent wallet instead"
 									}
 								});
 								return;
@@ -5014,9 +5326,34 @@ function createGatewayHttpServer(opts) {
 					}
 					const agentId = typeof payload.agentId === "string" ? payload.agentId.trim() : "";
 					if (agentId) {
+						const assignedWalletId = typeof payload.walletId === "string" ? payload.walletId.trim() : "";
+						if (assignedWalletId) {
+							const registry = readWalletProviderRegistry(process.env);
+							const wallet = registry.wallets.find((entry) => entry.id === assignedWalletId);
+							if (!wallet) {
+								sendLoginResponse(404, {
+									ok: false,
+									error: {
+										code: "wallet_not_found",
+										message: "walletId does not exist"
+									}
+								});
+								return;
+							}
+							if (resolveWalletUserRole(wallet) !== "agent") {
+								sendLoginResponse(409, {
+									ok: false,
+									error: {
+										code: "wallet_purpose_locked",
+										message: "only an explicit Agent wallet can be assigned to an Agent"
+									}
+								});
+								return;
+							}
+						}
 						setAgentWalletAssignment({
 							agentId,
-							walletId: typeof payload.walletId === "string" ? payload.walletId.trim() : undefined,
+							walletId: assignedWalletId || undefined,
 							env: process.env
 						});
 					}
@@ -5533,10 +5870,12 @@ function createGatewayHttpServer(opts) {
 					}
 				} };
 				statusPayload.wallets = registry.wallets.map((wallet) => {
+					const liveWallet = snapshot.wallets?.find((entry) => entry.id === wallet.id);
 					const solana = findWalletChainEntry(snapshotAny.chainWallets?.solana, wallet.id);
-					const readiness = {
+					const readiness = liveWallet?.readiness ?? {
 						keystore: Boolean(solana?.decryptReady ?? false),
-						rpc: Boolean(solana?.rpcConfigured)
+						rpc: Boolean(solana?.rpcConfigured),
+						ready: false
 					};
 					return {
 						id: wallet.id,
@@ -5548,7 +5887,7 @@ function createGatewayHttpServer(opts) {
 						readiness,
 						chains: wallet.addresses?.solana ? ["solana"] : [],
 						rpcConfigured: readiness.rpc,
-						health: readiness.keystore ? "ok" : "degraded"
+						health: readiness.ready ? "ok" : "degraded"
 					};
 				});
 				if (configuredProviderId === "local-socket-signer") {
@@ -7129,7 +7468,7 @@ function createGatewayHttpServer(opts) {
 					});
 					return;
 				}
-				if (operation !== "wallet.approve" && operation !== "wallet.policy" && operation !== "wallet.settings" && operation !== "wallet.provider-credentials" && operation !== "wallet.passkey-enroll" && operation !== "wallet.passkey-remove" && operation !== "wallet.reset" && operation !== "wallet.rotate" && operation !== "wallet.execution-mode" && operation !== "wallet.send" && operation !== "mining.capital" && operation !== "mining.policy") {
+				if (operation !== "wallet.approve" && operation !== "wallet.policy" && operation !== "wallet.settings" && operation !== "wallet.provider-credentials" && operation !== "wallet.network" && operation !== "wallet.archive" && operation !== "wallet.passkey-enroll" && operation !== "wallet.passkey-remove" && operation !== "wallet.reset" && operation !== "wallet.rotate" && operation !== "wallet.execution-mode" && operation !== "wallet.send" && operation !== "mining.capital" && operation !== "mining.policy") {
 					sendLoginResponse(400, {
 						ok: false,
 						error: {
@@ -7263,7 +7602,7 @@ function createGatewayHttpServer(opts) {
 				const payloadRaw = body.value ?? {};
 				const requestId = typeof payloadRaw.requestId === "string" ? payloadRaw.requestId.trim() || undefined : undefined;
 				const operation = typeof payloadRaw.operation === "string" ? payloadRaw.operation.trim() || undefined : undefined;
-				if (operation && operation !== "wallet.approve" && operation !== "wallet.policy" && operation !== "wallet.settings" && operation !== "wallet.provider-credentials" && operation !== "wallet.passkey-enroll" && operation !== "wallet.passkey-remove" && operation !== "wallet.reset" && operation !== "wallet.rotate" && operation !== "wallet.execution-mode" && operation !== "wallet.send" && operation !== "mining.capital" && operation !== "mining.policy") {
+				if (operation && operation !== "wallet.approve" && operation !== "wallet.policy" && operation !== "wallet.settings" && operation !== "wallet.provider-credentials" && operation !== "wallet.network" && operation !== "wallet.archive" && operation !== "wallet.passkey-enroll" && operation !== "wallet.passkey-remove" && operation !== "wallet.reset" && operation !== "wallet.rotate" && operation !== "wallet.execution-mode" && operation !== "wallet.send" && operation !== "mining.capital" && operation !== "mining.policy") {
 					sendLoginResponse(400, {
 						ok: false,
 						error: {