@fased/fased 0.1.67 → 0.1.69

package/dist/commands/wallet.js

@@ -3,21 +3,23 @@ import { loadConfig, writeConfigFile } from "../config/io.js";
 import "../config/config.js";
 import { hasLegacyEmbeddedKeystoreConfig, hasLegacyEmbeddedKeystoreMaterialHint, throwLegacyEmbeddedKeystoreMigrationRequired } from "../wallet/legacy-embedded-keystore.js";
 import { ensureWalletStateDir, isLocalSignerExternallyManaged, resolveLocalSignerControlSocketPath, resolveLocalSignerMasterKeyPath, resolveLocalSignerSidecarPaths, resolveLocalSignerSocketPath, resolveLocalSignerStateDbPath } from "../wallet/wallet-runtime-config.js";
-import { normalizeWalletUserRole, readWalletProviderRegistry, resolveWalletUserRole, setDefaultWallet, setNamedWalletRole, setWalletProviderEnabled, upsertNamedWallet } from "../wallet/wallet-provider-registry.js";
+import { normalizeWalletUserRole, readWalletProviderRegistry, replaceRetiredMiningWallet, resolveWalletUserRole, setDefaultWallet, setNamedWalletRole, setWalletProviderEnabled, upsertNamedWallet, writeWalletProviderRegistry } from "../wallet/wallet-provider-registry.js";
 import { buildWalletProviderCapabilityMatrix } from "../wallet/wallet-provider-capabilities.js";
 import { redactWalletDiagnosticText } from "../wallet/wallet-redaction.js";
 import { callLocalSocketSigner, probeLocalSocketSignerHealth, requireLocalSocketSignerPath } from "../wallet/providers/local-socket-signer-adapter.js";
 import { readWalletProviderSecretStatus, saveWalletProviderSecret } from "../wallet/wallet-secrets-store.js";
 import { createWalletProviderAdapter, resolveWalletProviderId } from "../wallet/wallet-provider-resolver.js";
-import { readWalletStatusSnapshot, resolveWalletConfigForRuntime } from "../wallet/wallet-status.js";
-import { createLockedSignerOwnedWallet } from "../wallet/local-socket-signer-lifecycle.js";
+import { activateSignerOwnedRoleBaseline, createRoleReadySignerOwnedWallet, readSignerOwnedWallet, readSignerOwnedWalletReadiness } from "../wallet/local-socket-signer-lifecycle.js";
 import { normalizeNativeSignerWalletId } from "../wallet/native-signer-wallet-id.js";
+import { readWalletStatusSnapshot, resolveWalletConfigForRuntime } from "../wallet/wallet-status.js";
+import { buildMiningRetirementEvidence, verifyMiningRecoveryPackage, writeMiningRetirementReceipt } from "../wallet/mining-wallet-retirement.js";
 import { configureSignerOwnedWalletNetwork } from "../wallet/signer-network-admin.js";
 import { listWalletInboundEvents, pollWalletInboundEvents, reconcileWalletInboundEvents } from "../wallet/wallet-inbound-events.js";
 import { buildWalletCanaryReport, runWalletProviderCanaryReport } from "../wallet/wallet-canary.js";
 import { installSignerdBinary, resolveSignerdBinaryPath, restartLocalSocketSigner, writeLocalSignerEnvFile } from "../wizard/onboarding.wallet.js";
 import fs from "node:fs";
 import path from "node:path";
+import { spawnSync } from "node:child_process";
 import { createInterface } from "node:readline/promises";
 
 //#region src/commands/wallet.ts
@@ -261,10 +263,6 @@ function rpcEnvKeyFor(chain, walletId) {
 	}
 	return "FASED_WALLET_SOLANA_RPC_URL";
 }
-function executionFallbackRpcEnvKeyFor(walletId) {
-	const suffix = walletIdEnvSuffix(walletId);
-	return suffix ? `FASED_WALLET_SOLANA_EXECUTION_FALLBACK_RPC_URL__${suffix}` : "FASED_WALLET_SOLANA_EXECUTION_FALLBACK_RPC_URL";
-}
 function resolveRpcUrlForChain(env, chain, walletId, explicit) {
 	const explicitValue = explicit?.trim();
 	if (explicitValue) {
@@ -381,17 +379,23 @@ async function createSignerOwnedWalletForSetup(params) {
 	const walletId = params.walletId?.trim() || params.role;
 	const hosted = String(params.env.FASED_HOST_PROFILE ?? "").trim().toLowerCase() === "hosting";
 	let cfg = ensureLocalSignerProviderConfig(loadConfig(), params.env);
-	if (!hosted) {
-		cfg = setConfigEnvVar(cfg, rpcEnvKeyFor(params.chain, walletId), params.rpcUrl);
-	}
-	await writeConfigFile(cfg);
 	const mergedEnv = {
 		...params.env,
 		...cfg.env?.vars
 	};
 	const socketPath = resolveLocalSignerSocketPath(mergedEnv);
 	const expectedSignerWalletId = normalizeNativeSignerWalletId(walletId);
-	const existingSignerIdCollision = findNativeSignerWalletIdCollision(readWalletProviderRegistry(params.env).wallets, walletId, expectedSignerWalletId);
+	const registeredWallets = readWalletProviderRegistry(params.env).wallets;
+	if (params.role === "mining") {
+		const activeMiningWallet = registeredWallets.find((entry) => {
+			const role = normalizeWalletUserRole(entry.metadata?.role ?? entry.metadata?.purpose);
+			return role === "mining" || entry.id === "mining";
+		});
+		if (activeMiningWallet && activeMiningWallet.id !== walletId) {
+			throw new Error(`Mining already has one active wallet (${activeMiningWallet.id}). Archive it after the safety checks or complete a reviewed replacement before creating ${walletId}.`);
+		}
+	}
+	const existingSignerIdCollision = findNativeSignerWalletIdCollision(registeredWallets, walletId, expectedSignerWalletId);
 	if (existingSignerIdCollision) {
 		throw new Error(`native signer wallet ID ${expectedSignerWalletId} is already registered as ${existingSignerIdCollision.id}; choose a distinct wallet ID`);
 	}
@@ -408,7 +412,14 @@ async function createSignerOwnedWalletForSetup(params) {
 	}
 	let result;
 	try {
-		result = await createLockedSignerOwnedWallet({
+		result = hosted && params.env.FASED_GATEWAY_SERVICE !== "1" ? invokeNativeSignerWalletCreate({
+			signerBinPath: "/opt/fased/signer/fased-signerd",
+			operatorSocketPath: "/run/fased-signerd/operator.sock",
+			walletId: expectedSignerWalletId,
+			role: params.role,
+			allowExisting: Boolean(params.options.force),
+			env: mergedEnv
+		}) : await createRoleReadySignerOwnedWallet({
 			socketPath,
 			walletId,
 			role: params.role,
@@ -416,7 +427,7 @@ async function createSignerOwnedWalletForSetup(params) {
 		});
 	} catch (error) {
 		if (hosted) {
-			throw new Error(`root-managed hosted signer wallet creation failed: ${error instanceof Error ? error.message : String(error)}. Repair only from the provider root console with the exact tagged, attested Hosting release; never run the app checkout with sudo.`, { cause: error });
+			throw new Error(`hosted signer wallet creation failed: ${error instanceof Error ? error.message : String(error)}. Confirm the operator socket and exact installed signer release are healthy, then retry the same wallet ID.`, { cause: error });
 		}
 		throw error;
 	}
@@ -428,16 +439,36 @@ async function createSignerOwnedWalletForSetup(params) {
 	if (signerIdCollision) {
 		throw new Error(`native signer wallet ID ${signerWalletId} is already registered as ${signerIdCollision.id}; choose a distinct wallet ID`);
 	}
-	const executionFallbackRpcUrl = hosted ? "" : [mergedEnv[executionFallbackRpcEnvKeyFor(walletId)], mergedEnv[walletIdEnvSuffix(walletId) ? `FASED_WALLET_SOLANA_WRITE_RPC_FALLBACK_URL__${walletIdEnvSuffix(walletId)}` : "FASED_WALLET_SOLANA_WRITE_RPC_FALLBACK_URL"]].map((value) => String(value ?? "").trim()).find(Boolean) ?? "";
-	const network = configureSignerOwnedWalletNetwork({
+	const operatorLifecycle = hosted && params.env.FASED_GATEWAY_SERVICE !== "1";
+	const network = operatorLifecycle ? invokeNativeSignerNetworkSetPrimary({
+		signerBinPath: "/opt/fased/signer/fased-signerd",
+		socketFlag: "--operator-socket",
+		socketPath: "/run/fased-signerd/operator.sock",
+		walletId: signerWalletId,
+		primaryRpcUrl: params.rpcUrl,
+		expectedVersion: 0,
+		env: mergedEnv
+	}) : await configureSignerOwnedWalletNetwork({
 		walletId: signerWalletId,
 		primaryRpcUrl: params.rpcUrl,
-		executionFallbackRpcUrl: executionFallbackRpcUrl || undefined,
 		env: mergedEnv,
-		signerBinPath: hosted ? undefined : resolveSignerdBinaryPath(mergedEnv),
-		controlSocketPath: hosted ? undefined : resolveLocalSignerControlSocketPath(mergedEnv)
+		socketPath
 	});
+	cfg = setConfigEnvVar(cfg, rpcEnvKeyFor(params.chain, walletId), params.rpcUrl);
 	await writeConfigFile(cfg);
+	const readiness = operatorLifecycle ? invokeNativeSignerWalletReadiness({
+		signerBinPath: "/opt/fased/signer/fased-signerd",
+		socketFlag: "--operator-socket",
+		socketPath: "/run/fased-signerd/operator.sock",
+		walletId: signerWalletId,
+		env: mergedEnv
+	}) : await readSignerOwnedWalletReadiness({
+		socketPath,
+		walletId: signerWalletId
+	});
+	if (!readiness.ready || readiness.walletId !== signerWalletId || readiness.publicKey !== result.wallet.publicKey || readiness.role !== params.role || readiness.baselineVersion !== 1 || readiness.policyHash !== result.policy.hash || readiness.policyVersion !== result.policy.version || readiness.networkHash !== network.hash || readiness.networkVersion !== network.version) {
+		throw new Error(`Setup incomplete: signer readiness does not match the created ${params.role} wallet lifecycle`);
+	}
 	const wallet = upsertNamedWallet({
 		walletId,
 		name: params.options.walletName || "Wallet",
@@ -450,18 +481,37 @@ async function createSignerOwnedWalletForSetup(params) {
 			signerWalletId,
 			policyHash: result.policy.hash,
 			policyVersion: result.policy.version,
-			policyState: "locked",
+			baselineVersion: readiness.baselineVersion,
+			policyState: "ready",
 			networkHash: network.hash,
 			networkVersion: network.version,
-			networkReady: network.ready
+			networkReady: network.ready,
+			operationLane: readiness.operationLane,
+			roleReady: readiness.ready
 		},
 		env: params.env
 	});
-	if (params.role === "agent") {
-		setDefaultWallet({
-			walletId: wallet.id,
-			env: params.env
-		});
+	if (params.role === "mining") {
+		const currentEntry = cfg.plugins?.entries?.["sat-mining"];
+		const currentSatConfig = currentEntry?.config && typeof currentEntry.config === "object" && !Array.isArray(currentEntry.config) ? currentEntry.config : {};
+		cfg = {
+			...cfg,
+			plugins: {
+				...cfg.plugins,
+				entries: {
+					...cfg.plugins?.entries,
+					"sat-mining": {
+						enabled: true,
+						...currentEntry,
+						config: {
+							...currentSatConfig,
+							walletId: wallet.id
+						}
+					}
+				}
+			}
+		};
+		await writeConfigFile(cfg);
 	}
 	if (params.options.json) {
 		params.runtime.log(JSON.stringify({
@@ -473,24 +523,582 @@ async function createSignerOwnedWalletForSetup(params) {
 			address: result.wallet.publicKey,
 			policyHash: result.policy.hash,
 			policyVersion: result.policy.version,
-			policyState: "locked",
+			baselineVersion: readiness.baselineVersion,
+			policyState: "ready",
 			networkVersion: network.version,
 			networkReady: network.ready,
-			...network.rootAdminRequired ? {
-				networkActivation: "root-admin-required",
-				rootCommand: network.rootCommand
-			} : {}
+			operationLane: readiness.operationLane,
+			roleReady: readiness.ready
 		}, null, 2));
 	} else {
 		params.runtime.log(`Signer wallet ID: ${signerWalletId}`);
 		params.runtime.log(`${params.chain.toUpperCase()} address: ${result.wallet.publicKey}`);
 		if (!params.options.noSignerHints) {
-			params.runtime.log("Signer-owned wallet created with a deny-all policy. Configure explicit operations, destinations, assets, and positive caps before sending.");
-			if (network.rootAdminRequired && network.rootCommand) {
-				params.runtime.log("Hosted wallet remains fail-closed until a root administrator activates its RPC network from a root-owned file:");
-				params.runtime.log(network.rootCommand);
-			}
+			params.runtime.log(`Role baseline active: ${params.role} v${readiness.baselineVersion} (${readiness.operationLane}).`);
+		}
+	}
+	return result;
+}
+function requireOwnerOnlySignerImportFile(rawPath) {
+	const importPath = path.resolve(rawPath.trim());
+	if (!rawPath.trim() || !path.isAbsolute(rawPath.trim()) || importPath !== rawPath.trim()) {
+		throw new Error("--import-file must be an absolute clean path");
+	}
+	const info = fs.lstatSync(importPath);
+	if (!info.isFile() || info.isSymbolicLink() || info.nlink !== 1) {
+		throw new Error("wallet import file must be one regular, non-symlink, single-link file");
+	}
+	if ((info.mode & 63) !== 0) {
+		throw new Error("wallet import file must be owner-only (chmod 600)");
+	}
+	const effectiveUid = process.geteuid?.();
+	if (effectiveUid !== undefined && info.uid !== effectiveUid) {
+		throw new Error("wallet import file must be owned by the current terminal user");
+	}
+	const fd = fs.openSync(importPath, fs.constants.O_RDONLY | fs.constants.O_NOFOLLOW);
+	try {
+		const opened = fs.fstatSync(fd);
+		if (!opened.isFile() || opened.nlink !== 1 || opened.dev !== info.dev || opened.ino !== info.ino || (opened.mode & 63) !== 0 || effectiveUid !== undefined && opened.uid !== effectiveUid) {
+			throw new Error("wallet import file changed or became unsafe before it could be read");
+		}
+		return {
+			path: importPath,
+			fd
+		};
+	} catch (error) {
+		fs.closeSync(fd);
+		throw error;
+	}
+}
+function parseNativeSignerImportResult(params) {
+	let value;
+	try {
+		value = JSON.parse(params.stdout.trim());
+	} catch {
+		throw new Error("native signer import returned invalid JSON");
+	}
+	if (!value || typeof value !== "object" || Array.isArray(value)) {
+		throw new Error("native signer import returned an invalid result");
+	}
+	const result = value;
+	if (result.wallet?.walletId !== params.walletId || typeof result.wallet.publicKey !== "string" || !result.wallet.publicKey.trim() || !Number.isSafeInteger(result.wallet.version) || result.policy?.walletId !== params.walletId || result.policy.role !== params.role || result.policy.version !== 1 || result.policy.baselineVersion !== 1 || !result.policy.operations?.length || !result.policy.programs?.length || !result.policy.assets?.length || typeof result.policy.hash !== "string" || !/^sha256:[0-9a-f]{64}$/.test(result.policy.hash)) {
+		throw new Error("native signer import did not return an active signer-owned role baseline");
+	}
+	return result;
+}
+function invokeNativeSignerWalletImport(params) {
+	const input = requireOwnerOnlySignerImportFile(params.importFile);
+	const command = params.signerBinPath;
+	const args = [
+		"admin",
+		"wallet",
+		"import",
+		params.hosted ? "--operator-socket" : "--control-socket",
+		params.controlSocketPath,
+		"--wallet-id",
+		params.walletId,
+		"--baseline-role",
+		params.role
+	];
+	try {
+		const child = spawnSync(command, args, {
+			env: {
+				HOME: params.env.HOME,
+				LANG: params.env.LANG || "C.UTF-8",
+				PATH: "/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin"
+			},
+			stdio: [
+				input.fd,
+				"pipe",
+				"pipe"
+			],
+			encoding: "utf8",
+			maxBuffer: 256 * 1024,
+			timeout: 3e4
+		});
+		if (child.error) {
+			throw child.error;
+		}
+		if (child.status !== 0) {
+			const detail = String(child.stderr || "native signer import failed").trim();
+			throw new Error(redactWalletDiagnosticText(detail));
+		}
+		return parseNativeSignerImportResult({
+			stdout: String(child.stdout ?? ""),
+			walletId: params.walletId,
+			role: params.role
+		});
+	} finally {
+		fs.closeSync(input.fd);
+	}
+}
+function nativeSignerLifecycleEnv(env) {
+	return {
+		HOME: env.HOME,
+		LANG: env.LANG || "C.UTF-8",
+		PATH: "/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin"
+	};
+}
+function invokeNativeSignerWalletCreate(params) {
+	const child = spawnSync(params.signerBinPath, [
+		"admin",
+		"wallet",
+		"create",
+		"--operator-socket",
+		params.operatorSocketPath,
+		"--wallet-id",
+		params.walletId,
+		"--baseline-role",
+		params.role,
+		...params.allowExisting ? ["--allow-existing"] : []
+	], {
+		env: nativeSignerLifecycleEnv(params.env),
+		stdio: [
+			"ignore",
+			"pipe",
+			"pipe"
+		],
+		encoding: "utf8",
+		maxBuffer: 256 * 1024,
+		timeout: 3e4
+	});
+	if (child.error) {
+		throw child.error;
+	}
+	if (child.status !== 0) {
+		throw new Error(redactWalletDiagnosticText(String(child.stderr || "native signer create failed").trim()));
+	}
+	return parseNativeSignerImportResult({
+		stdout: String(child.stdout ?? ""),
+		walletId: params.walletId,
+		role: params.role
+	});
+}
+function invokeNativeSignerNetworkSetPrimary(params) {
+	const input = JSON.stringify({ primaryRpcUrl: params.primaryRpcUrl });
+	const child = spawnSync(params.signerBinPath, [
+		"admin",
+		"network",
+		"set-primary",
+		params.socketFlag,
+		params.socketPath,
+		"--wallet-id",
+		params.walletId,
+		"--expected-version",
+		String(params.expectedVersion)
+	], {
+		env: nativeSignerLifecycleEnv(params.env),
+		input,
+		stdio: [
+			"pipe",
+			"pipe",
+			"pipe"
+		],
+		encoding: "utf8",
+		maxBuffer: 256 * 1024,
+		timeout: 6e4
+	});
+	if (child.error) {
+		throw child.error;
+	}
+	if (child.status !== 0) {
+		throw new Error(redactWalletDiagnosticText(String(child.stderr || "native signer RPC update failed").trim()));
+	}
+	let result;
+	try {
+		result = JSON.parse(String(child.stdout ?? ""));
+	} catch {
+		throw new Error("native signer RPC update returned invalid JSON");
+	}
+	const record = result;
+	if (!record || record.walletId !== params.walletId || record.configured !== true || record.ready !== true || !Number.isSafeInteger(record.version) || typeof record.hash !== "string" || !/^hmac-sha256:[0-9a-f]{64}$/.test(record.hash)) {
+		throw new Error("native signer RPC update returned an invalid readiness summary");
+	}
+	return {
+		walletId: String(record.walletId),
+		configured: true,
+		ready: true,
+		version: Number(record.version),
+		hash: String(record.hash)
+	};
+}
+function invokeNativeSignerWalletReadiness(params) {
+	const child = spawnSync(params.signerBinPath, [
+		"admin",
+		"wallet",
+		"readiness",
+		params.socketFlag,
+		params.socketPath,
+		"--wallet-id",
+		params.walletId
+	], {
+		env: nativeSignerLifecycleEnv(params.env),
+		stdio: [
+			"ignore",
+			"pipe",
+			"pipe"
+		],
+		encoding: "utf8",
+		maxBuffer: 256 * 1024,
+		timeout: 3e4
+	});
+	if (child.error) {
+		throw child.error;
+	}
+	if (child.status !== 0) {
+		throw new Error(redactWalletDiagnosticText(String(child.stderr || "native signer readiness failed").trim()));
+	}
+	let result;
+	try {
+		result = JSON.parse(String(child.stdout ?? ""));
+	} catch {
+		throw new Error("native signer readiness returned invalid JSON");
+	}
+	const readiness = result;
+	if (!readiness || readiness.walletId !== params.walletId || typeof readiness.publicKey !== "string" || !Number.isSafeInteger(readiness.walletVersion) || typeof readiness.role !== "string" || !Number.isSafeInteger(readiness.policyVersion) || !Number.isSafeInteger(readiness.networkVersion) || typeof readiness.ready !== "boolean") {
+		throw new Error("native signer readiness returned an invalid result");
+	}
+	return readiness;
+}
+function invokeNativeSignerJSON(params) {
+	const child = spawnSync(params.signerBinPath, params.args, {
+		env: nativeSignerLifecycleEnv(params.env),
+		input: params.input,
+		stdio: [
+			params.input === undefined ? "ignore" : "pipe",
+			"pipe",
+			"pipe"
+		],
+		encoding: "utf8",
+		maxBuffer: 512 * 1024,
+		timeout: 12e4
+	});
+	if (child.error) {
+		throw child.error;
+	}
+	if (child.status !== 0) {
+		throw new Error(redactWalletDiagnosticText(String(child.stderr || `${params.label} failed`).trim()));
+	}
+	let parsed;
+	try {
+		parsed = JSON.parse(String(child.stdout ?? ""));
+	} catch {
+		throw new Error(`${params.label} returned invalid JSON`);
+	}
+	if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+		throw new Error(`${params.label} returned an invalid result`);
+	}
+	return parsed;
+}
+function invokeNativeSignerBalance(params) {
+	const result = invokeNativeSignerJSON({
+		signerBinPath: params.signerBinPath,
+		args: [
+			"admin",
+			"wallet",
+			"balance",
+			params.socketFlag,
+			params.socketPath,
+			"--wallet-id",
+			params.walletId
+		],
+		env: params.env,
+		label: "native signer balance lookup"
+	});
+	const balance = typeof result.balance === "string" ? result.balance : "";
+	if (result.address !== params.publicKey || result.chain !== "solana" || result.unit !== "lamports" || !/^\d+$/u.test(balance)) {
+		throw new Error("native signer balance lookup returned an invalid result");
+	}
+	return balance;
+}
+function parseNativeSignerRotation(value) {
+	if (typeof value.rotationId !== "string" || !/^sha256:[0-9a-f]{64}$/u.test(value.rotationId) || typeof value.sourceWalletId !== "string" || typeof value.sourcePublicKey !== "string" || typeof value.successorWalletId !== "string" || typeof value.successorPublicKey !== "string" || value.state !== "prepared" && value.state !== "committed" || !Number.isSafeInteger(value.version)) {
+		throw new Error("native signer rotation returned an invalid result");
+	}
+	return value;
+}
+function invokeNativeSignerRotationCreate(params) {
+	return parseNativeSignerRotation(invokeNativeSignerJSON({
+		signerBinPath: params.signerBinPath,
+		args: [
+			"admin",
+			"wallet",
+			"rotate-successor",
+			params.socketFlag,
+			params.socketPath,
+			"--wallet-id",
+			params.sourceWalletId,
+			"--successor-wallet-id",
+			params.successorWalletId,
+			"--expected-source-public-key",
+			params.sourcePublicKey,
+			"--expected-source-wallet-version",
+			String(params.sourceWalletVersion),
+			"--expected-source-policy-version",
+			String(params.sourcePolicyVersion)
+		],
+		env: params.env,
+		label: "native signer Mining successor preparation"
+	}));
+}
+function invokeNativeSignerRotationStatus(params) {
+	try {
+		return parseNativeSignerRotation(invokeNativeSignerJSON({
+			signerBinPath: params.signerBinPath,
+			args: [
+				"admin",
+				"wallet",
+				"rotation-status",
+				params.socketFlag,
+				params.socketPath,
+				"--wallet-id",
+				params.sourceWalletId
+			],
+			env: params.env,
+			label: "native signer Mining rotation status"
+		}));
+	} catch (error) {
+		const message = error instanceof Error ? error.message : String(error);
+		if (/rotation.*not found/iu.test(message)) {
+			return null;
+		}
+		throw error;
+	}
+}
+function invokeNativeSignerRotationCommit(params) {
+	const rotation = params.rotation;
+	return parseNativeSignerRotation(invokeNativeSignerJSON({
+		signerBinPath: params.signerBinPath,
+		args: [
+			"admin",
+			"wallet",
+			"rotation-commit",
+			params.socketFlag,
+			params.socketPath,
+			"--wallet-id",
+			rotation.sourceWalletId,
+			"--successor-wallet-id",
+			rotation.successorWalletId,
+			"--rotation-id",
+			rotation.rotationId,
+			"--expected-source-public-key",
+			rotation.sourcePublicKey,
+			"--expected-successor-public-key",
+			rotation.successorPublicKey,
+			"--expected-source-wallet-version",
+			String(rotation.prepareExpectedSourceWalletVersion),
+			"--expected-source-policy-version",
+			String(rotation.prepareExpectedSourcePolicyVersion),
+			"--expected-successor-wallet-version",
+			"1",
+			"--expected-successor-policy-version",
+			"1",
+			"--expected-rotation-version",
+			"1",
+			"--expected-successor-network-version",
+			String(params.successorNetworkVersion),
+			"--expected-successor-network-hash",
+			params.successorNetworkHash
+		],
+		input: JSON.stringify({
+			recoveryPackageHash: params.recoveryPackageHash,
+			safetyEvidence: params.safetyEvidence
+		}),
+		env: params.env,
+		label: "native signer Mining retirement commit"
+	}));
+}
+function invokeNativeSignerRecoveryImport(params) {
+	const input = requireOwnerOnlySignerImportFile(params.recoveryFile);
+	try {
+		const child = spawnSync(params.signerBinPath, [
+			"admin",
+			"wallet",
+			"recovery-import",
+			params.hosted ? "--operator-socket" : "--control-socket",
+			params.controlSocketPath,
+			"--wallet-id",
+			params.walletId,
+			"--baseline-role",
+			params.role,
+			"--recovery-file",
+			input.path
+		], {
+			env: {
+				HOME: params.env.HOME,
+				LANG: params.env.LANG || "C.UTF-8",
+				PATH: "/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin"
+			},
+			stdio: [
+				"inherit",
+				"pipe",
+				"pipe"
+			],
+			encoding: "utf8",
+			maxBuffer: 256 * 1024,
+			timeout: 12e4
+		});
+		if (child.error) {
+			throw child.error;
+		}
+		if (child.status !== 0) {
+			const detail = String(child.stderr || "native signer recovery import failed").trim();
+			throw new Error(redactWalletDiagnosticText(detail));
+		}
+		return parseNativeSignerImportResult({
+			stdout: String(child.stdout ?? ""),
+			walletId: params.walletId,
+			role: params.role
+		});
+	} finally {
+		fs.closeSync(input.fd);
+	}
+}
+async function importSignerOwnedWalletForSetup(params) {
+	if (params.chain !== "solana") {
+		throw new Error("fased-signerd protocol v2 currently supports Solana wallet import only");
+	}
+	const hosted = String(params.env.FASED_HOST_PROFILE ?? "").trim().toLowerCase() === "hosting";
+	let cfg = ensureLocalSignerProviderConfig(loadConfig(), params.env);
+	const mergedEnv = {
+		...params.env,
+		...cfg.env?.vars
+	};
+	const socketPath = resolveLocalSignerSocketPath(mergedEnv);
+	const signerWalletId = normalizeNativeSignerWalletId(params.walletId);
+	const registeredWallets = readWalletProviderRegistry(params.env).wallets;
+	if (params.role === "mining" && registeredWallets.some((entry) => {
+		const role = normalizeWalletUserRole(entry.metadata?.role ?? entry.metadata?.purpose);
+		return (role === "mining" || entry.id === "mining") && entry.id !== params.walletId;
+	})) {
+		throw new Error("Mining already has one active wallet. Complete the guarded Archive/Replace flow first.");
+	}
+	const collision = findNativeSignerWalletIdCollision(registeredWallets, params.walletId, signerWalletId);
+	if (collision) {
+		throw new Error(`native signer wallet ID ${signerWalletId} is already registered as ${collision.id}; choose a distinct wallet ID`);
+	}
+	const signerBinPath = hosted ? "/opt/fased/signer/fased-signerd" : resolveSignerdBinaryPath(mergedEnv);
+	const controlSocketPath = hosted ? "/run/fased-signerd/operator.sock" : resolveLocalSignerControlSocketPath(mergedEnv);
+	if (!hosted) {
+		writeLocalSignerEnvFile({
+			config: cfg,
+			env: mergedEnv
+		});
+		if (!fs.existsSync(signerBinPath)) {
+			installSignerdBinary(signerBinPath);
 		}
+		await restartLocalSocketSigner(undefined, mergedEnv);
+	}
+	const result = params.options.mode === "local-signer-recovery-import" ? invokeNativeSignerRecoveryImport({
+		hosted,
+		signerBinPath,
+		controlSocketPath,
+		walletId: signerWalletId,
+		role: params.role,
+		recoveryFile: params.importFile,
+		env: mergedEnv
+	}) : invokeNativeSignerWalletImport({
+		hosted,
+		signerBinPath,
+		controlSocketPath,
+		walletId: signerWalletId,
+		role: params.role,
+		importFile: params.importFile,
+		env: mergedEnv
+	});
+	const network = hosted ? invokeNativeSignerNetworkSetPrimary({
+		signerBinPath,
+		socketFlag: "--operator-socket",
+		socketPath: controlSocketPath,
+		walletId: signerWalletId,
+		primaryRpcUrl: params.rpcUrl,
+		expectedVersion: 0,
+		env: mergedEnv
+	}) : await configureSignerOwnedWalletNetwork({
+		walletId: signerWalletId,
+		primaryRpcUrl: params.rpcUrl,
+		env: mergedEnv,
+		socketPath
+	});
+	cfg = setConfigEnvVar(cfg, rpcEnvKeyFor(params.chain, params.walletId), params.rpcUrl);
+	await writeConfigFile(cfg);
+	const readiness = hosted ? invokeNativeSignerWalletReadiness({
+		signerBinPath,
+		socketFlag: "--operator-socket",
+		socketPath: controlSocketPath,
+		walletId: signerWalletId,
+		env: mergedEnv
+	}) : await readSignerOwnedWalletReadiness({
+		socketPath,
+		walletId: signerWalletId
+	});
+	if (!readiness.ready || readiness.publicKey !== result.wallet.publicKey || readiness.role !== params.role || readiness.baselineVersion !== 1 || readiness.policyHash !== result.policy.hash || readiness.policyVersion !== result.policy.version || readiness.networkHash !== network.hash || readiness.networkVersion !== network.version) {
+		throw new Error(`Setup incomplete: signer readiness does not match the imported ${params.role} wallet lifecycle`);
+	}
+	const wallet = upsertNamedWallet({
+		walletId: params.walletId,
+		name: params.options.walletName || "Wallet",
+		providerId: "local-socket-signer",
+		addresses: { solana: result.wallet.publicKey },
+		metadata: {
+			role: params.role,
+			purpose: params.role,
+			keyAuthority: "signer-owned-v2",
+			signerWalletId,
+			policyHash: result.policy.hash,
+			policyVersion: result.policy.version,
+			baselineVersion: readiness.baselineVersion,
+			policyState: "ready",
+			networkHash: network.hash,
+			networkVersion: network.version,
+			networkReady: network.ready,
+			operationLane: readiness.operationLane,
+			roleReady: readiness.ready
+		},
+		env: params.env
+	});
+	if (params.role === "mining") {
+		const currentEntry = cfg.plugins?.entries?.["sat-mining"];
+		const currentConfig = currentEntry?.config && typeof currentEntry.config === "object" && !Array.isArray(currentEntry.config) ? currentEntry.config : {};
+		cfg = {
+			...cfg,
+			plugins: {
+				...cfg.plugins,
+				entries: {
+					...cfg.plugins?.entries,
+					"sat-mining": {
+						enabled: true,
+						...currentEntry,
+						config: {
+							...currentConfig,
+							walletId: wallet.id
+						}
+					}
+				}
+			}
+		};
+		await writeConfigFile(cfg);
+	}
+	if (params.options.json) {
+		params.runtime.log(JSON.stringify({
+			ok: true,
+			provider: "local-socket-signer",
+			imported: true,
+			walletId: wallet.id,
+			signerWalletId,
+			role: params.role,
+			address: result.wallet.publicKey,
+			baselineVersion: readiness.baselineVersion,
+			policyState: "ready",
+			networkVersion: network.version,
+			networkReady: network.ready,
+			operationLane: readiness.operationLane,
+			roleReady: readiness.ready
+		}, null, 2));
+	} else {
+		params.runtime.log(`Imported ${params.role} wallet ${wallet.id} into fased-signerd.`);
+		params.runtime.log(`SOLANA address: ${result.wallet.publicKey}`);
+		params.runtime.log(`Readiness: ${readiness.ready ? "ready" : "setup incomplete"} (${readiness.operationLane})`);
 	}
 	return result;
 }
@@ -591,27 +1199,32 @@ async function walletSetupCommand(runtime = defaultRuntime, options = {}) {
 	if (!mode) {
 		runtime.log("Wallet setup modes:");
 		runtime.log("  local-signer-create  Create a signer-owned Solana wallet (default)");
-		runtime.log("  local-signer-import  Show the native signer-only import command");
+		runtime.log("  local-signer-import  Import an owner-only Solana keypair into the signer");
+		runtime.log("  local-signer-recovery-import  Restore an encrypted signer recovery package");
 		runtime.log("  turnkey          Configure hosted provider (Turnkey)");
 		runtime.log("  alchemy          Configure hosted provider (Alchemy)");
 		const picked = await prompt("Choose wallet setup mode", "local-signer-create");
-		mode = picked === "local-signer-create" || picked === "local-signer-import" || picked === "local-signer" || picked === "turnkey" || picked === "alchemy" ? picked : "local-signer-create";
+		mode = picked === "local-signer-create" || picked === "local-signer-import" || picked === "local-signer-recovery-import" || picked === "local-signer" || picked === "turnkey" || picked === "alchemy" ? picked : "local-signer-create";
 	}
 	if (mode === "embedded" || mode === "embedded-create" || mode === "embedded-import") {
 		throwLegacyEmbeddedKeystoreMigrationRequired(`wallet setup mode ${mode} is unavailable`);
 	}
-	if (mode !== "local-signer-create" && mode !== "local-signer-import" && mode !== "local-signer" && mode !== "turnkey" && mode !== "alchemy" && mode !== "privy") {
-		throw new Error(`Unsupported wallet setup mode: ${String(mode)}. ` + "Use one of: local-signer-create, local-signer-import, local-signer, turnkey, alchemy. Privy is unavailable.");
+	if (mode !== "local-signer-create" && mode !== "local-signer-import" && mode !== "local-signer-recovery-import" && mode !== "local-signer" && mode !== "turnkey" && mode !== "alchemy" && mode !== "privy") {
+		throw new Error(`Unsupported wallet setup mode: ${String(mode)}. ` + "Use one of: local-signer-create, local-signer-import, local-signer-recovery-import, local-signer, turnkey, alchemy. Privy is unavailable.");
 	}
 	if (mode === "local-signer-create") {
 		const chain = options.chain ?? "solana";
-		const walletId = options.walletId ?? ((await prompt("Wallet id (optional, e.g. agent/mining/vault)", "")).trim() || undefined);
+		const roleInput = options.role ?? (interactive ? await prompt("Wallet role (agent|mining|vault)", "") : "");
+		const role = normalizeWalletUserRole(roleInput);
+		if (!role) {
+			throw new Error("--role is required for non-interactive wallet creation and must be agent, mining, or vault");
+		}
+		const walletId = options.walletId ?? ((await prompt("Wallet id", role)).trim() || role);
 		const rpcUrlFallback = resolveRpcUrlForChain(env, chain, walletId, options.rpcUrl);
 		const rpcUrl = (await prompt(`${chain.toUpperCase()} RPC URL (required for balances/readiness/send)`, rpcUrlFallback)).trim();
 		if (!rpcUrl) {
 			throw new Error(`${chain.toUpperCase()} RPC URL is required for self-hosted wallet setup. ` + "Pass --rpc-url or set FASED_WALLET_<CHAIN>_RPC_URL.");
 		}
-		const role = normalizeWalletUserRole(options.role) ?? (walletId?.trim().toLowerCase() === "mining" ? "mining" : walletId?.trim().toLowerCase() === "vault" ? "vault" : "agent");
 		await createSignerOwnedWalletForSetup({
 			runtime,
 			options,
@@ -627,35 +1240,35 @@ async function walletSetupCommand(runtime = defaultRuntime, options = {}) {
 		await configureLimitOrdersIfRequested();
 		return;
 	}
-	if (mode === "local-signer-import") {
-		const walletId = normalizeNativeSignerWalletId(options.walletId ?? "agent");
-		const role = normalizeWalletUserRole(options.role) ?? (walletId === "mining" ? "mining" : walletId === "vault" ? "vault" : "agent");
-		const hosted = String(env.FASED_HOST_PROFILE ?? "").trim().toLowerCase() === "hosting";
-		const config = loadConfig();
-		const effectiveEnv = {
-			...env,
-			...config.env?.vars
-		};
-		if (!hosted) {
-			writeLocalSignerEnvFile({
-				config,
-				env: effectiveEnv
-			});
-			const signerBinPath = resolveSignerdBinaryPath(effectiveEnv);
-			if (!fs.existsSync(signerBinPath)) {
-				installSignerdBinary(signerBinPath);
-			}
-			await restartLocalSocketSigner(undefined, effectiveEnv);
-		}
-		const signerBinary = hosted ? "/opt/fased/signer/fased-signerd" : resolveSignerdBinaryPath(effectiveEnv);
-		const controlSocket = hosted ? "/run/fased-signerd/control.sock" : resolveLocalSignerControlSocketPath(effectiveEnv);
-		runtime.log("Wallet import is native-signer-only; Fased Node will not read the key or passphrase.");
-		runtime.log("Solana CLI keypair import:");
-		runtime.log(`chmod 600 /absolute/path/to/solana-keypair.json && ${signerBinary} admin wallet import --control-socket ${controlSocket} --wallet-id ${walletId} --locked-role ${role} < /absolute/path/to/solana-keypair.json`);
-		runtime.log("Legacy encrypted Fased keystore migration:");
-		runtime.log(`chmod 600 /absolute/path/to/keystore-solana.v1.enc /absolute/path/to/passphrase && ${signerBinary} admin wallet import-legacy --control-socket ${controlSocket} --wallet-id ${walletId} --locked-role ${role} --keystore-path /absolute/path/to/keystore-solana.v1.enc --passphrase-path /absolute/path/to/passphrase`);
-		runtime.log(`After verifying the returned public address, run: fased wallet finalize-legacy-migration --wallet-id ${options.walletId ?? walletId}`);
-		runtime.log("Never put a private key or passphrase in the dashboard, Gateway, chat, argv, or an environment variable.");
+	if (mode === "local-signer-import" || mode === "local-signer-recovery-import") {
+		const roleInput = options.role ?? (interactive ? await prompt("Wallet role (agent|mining|vault)", "") : "");
+		const role = normalizeWalletUserRole(roleInput);
+		if (!role) {
+			throw new Error("--role is required for non-interactive wallet import and must be agent, mining, or vault");
+		}
+		const friendlyWalletId = options.walletId ?? (interactive ? await prompt("Wallet id", role) : role);
+		const walletId = friendlyWalletId.trim() || role;
+		const recoveryImport = mode === "local-signer-recovery-import";
+		const importFile = ((recoveryImport ? options.recoveryFile : options.importFile) ?? (interactive ? await prompt(recoveryImport ? "Absolute path to owner-only encrypted recovery package" : "Absolute path to owner-only Solana keypair JSON", "") : "")).trim();
+		if (!importFile) {
+			throw new Error(recoveryImport ? "--recovery-file is required for non-interactive native recovery import" : "--import-file is required for non-interactive native wallet import");
+		}
+		const chain = options.chain ?? "solana";
+		const rpcUrlFallback = resolveRpcUrlForChain(env, chain, walletId, options.rpcUrl);
+		const rpcUrl = (await prompt(`${chain.toUpperCase()} RPC URL (one primary execution RPC)`, rpcUrlFallback)).trim();
+		if (!rpcUrl) {
+			throw new Error("--rpc-url is required for non-interactive native wallet import");
+		}
+		await importSignerOwnedWalletForSetup({
+			runtime,
+			options,
+			env,
+			chain,
+			walletId,
+			rpcUrl,
+			role,
+			importFile
+		});
 		return;
 	}
 	if (mode === "local-signer") {
@@ -743,6 +1356,465 @@ async function walletSetupCommand(runtime = defaultRuntime, options = {}) {
 		return;
 	}
 }
+async function walletRpcSetCommand(runtime = defaultRuntime, options) {
+	const walletId = options.walletId.trim();
+	const rpcUrl = options.rpcUrl.trim();
+	if (!walletId) {
+		throw new Error("--wallet-id is required");
+	}
+	if (!rpcUrl) {
+		throw new Error("--rpc-url is required");
+	}
+	const cfg = loadConfig();
+	const effectiveEnv = {
+		...process.env,
+		...cfg.env?.vars
+	};
+	const registry = readWalletProviderRegistry(effectiveEnv);
+	const wallet = registry.wallets.find((entry) => entry.id === walletId);
+	if (!wallet || wallet.providerId !== "local-socket-signer") {
+		throw new Error(`native signer wallet not found: ${walletId}`);
+	}
+	const signerWalletId = typeof wallet.metadata?.signerWalletId === "string" && wallet.metadata.signerWalletId.trim() ? wallet.metadata.signerWalletId.trim() : normalizeNativeSignerWalletId(wallet.id);
+	const hosted = String(effectiveEnv.FASED_HOST_PROFILE ?? "").trim().toLowerCase() === "hosting";
+	const signerBinPath = hosted ? "/opt/fased/signer/fased-signerd" : resolveSignerdBinaryPath(effectiveEnv);
+	const socketFlag = hosted ? "--operator-socket" : "--control-socket";
+	const socketPath = hosted ? "/run/fased-signerd/operator.sock" : resolveLocalSignerControlSocketPath(effectiveEnv);
+	const current = hosted ? invokeNativeSignerWalletReadiness({
+		signerBinPath,
+		socketFlag,
+		socketPath,
+		walletId: signerWalletId,
+		env: effectiveEnv
+	}) : await readSignerOwnedWalletReadiness({
+		socketPath: resolveLocalSignerSocketPath(effectiveEnv),
+		walletId: signerWalletId
+	});
+	const network = invokeNativeSignerNetworkSetPrimary({
+		signerBinPath,
+		socketFlag,
+		socketPath,
+		walletId: signerWalletId,
+		primaryRpcUrl: rpcUrl,
+		expectedVersion: current.networkVersion,
+		env: effectiveEnv
+	});
+	const nextConfig = setConfigEnvVar(cfg, rpcEnvKeyFor("solana", walletId), rpcUrl);
+	await writeConfigFile(nextConfig);
+	registry.wallets = registry.wallets.map((entry) => entry.id === wallet.id ? {
+		...entry,
+		metadata: {
+			...entry.metadata,
+			networkHash: network.hash,
+			networkVersion: network.version,
+			networkReady: network.ready
+		},
+		updatedAt: new Date().toISOString()
+	} : entry);
+	writeWalletProviderRegistry(registry, effectiveEnv);
+	if (options.json) {
+		runtime.log(JSON.stringify({
+			ok: true,
+			network
+		}, null, 2));
+		return;
+	}
+	runtime.log(`Primary Solana RPC verified for ${wallet.name} (${wallet.id}); signer network v${network.version} is ready.`);
+}
+async function walletRecoveryExportCommand(runtime = defaultRuntime, options) {
+	const walletId = options.walletId.trim();
+	const output = options.output.trim();
+	if (!walletId) {
+		throw new Error("--wallet-id is required");
+	}
+	if (!output || !path.isAbsolute(output) || path.resolve(output) !== output) {
+		throw new Error("--output must be an absolute clean path for a new recovery file");
+	}
+	const cfg = loadConfig();
+	const effectiveEnv = {
+		...process.env,
+		...cfg.env?.vars
+	};
+	const wallet = readWalletProviderRegistry(effectiveEnv).wallets.find((entry) => entry.id === walletId);
+	if (!wallet || wallet.providerId !== "local-socket-signer") {
+		throw new Error(`native signer wallet not found: ${walletId}`);
+	}
+	const publicKey = wallet.addresses?.solana?.trim() || "";
+	if (!publicKey) {
+		throw new Error(`native signer wallet ${walletId} has no verified Solana public address`);
+	}
+	const hosted = String(effectiveEnv.FASED_HOST_PROFILE ?? "").trim().toLowerCase() === "hosting";
+	const signerWalletId = typeof wallet.metadata?.signerWalletId === "string" && wallet.metadata.signerWalletId.trim() ? wallet.metadata.signerWalletId.trim() : normalizeNativeSignerWalletId(wallet.id);
+	const signerBinPath = hosted ? "/opt/fased/signer/fased-signerd" : resolveSignerdBinaryPath(effectiveEnv);
+	const controlSocketPath = hosted ? "/run/fased-signerd/operator.sock" : resolveLocalSignerControlSocketPath(effectiveEnv);
+	runtime.log(`Creating encrypted recovery package for ${wallet.id}. The signer will ask for and confirm the recovery password without echoing it.`);
+	const child = spawnSync(signerBinPath, [
+		"admin",
+		"wallet",
+		"recovery-export",
+		hosted ? "--operator-socket" : "--control-socket",
+		controlSocketPath,
+		"--wallet-id",
+		signerWalletId,
+		"--expected-public-key",
+		publicKey,
+		"--output",
+		output
+	], {
+		env: {
+			HOME: effectiveEnv.HOME,
+			LANG: effectiveEnv.LANG || "C.UTF-8",
+			PATH: "/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin"
+		},
+		stdio: "inherit",
+		timeout: 12e4
+	});
+	if (child.error) {
+		throw child.error;
+	}
+	if (child.status !== 0) {
+		throw new Error(`encrypted recovery export failed with exit code ${child.status ?? "unknown"}`);
+	}
+	runtime.log(`Encrypted recovery package written: ${output} (owner-only)`);
+	runtime.log(`Wallet: ${wallet.id} · Role: ${resolveWalletUserRole(wallet)} · Address: ${publicKey}`);
+}
+async function walletRecoveryImportCommand(runtime = defaultRuntime, options) {
+	await walletSetupCommand(runtime, {
+		mode: "local-signer-recovery-import",
+		chain: "solana",
+		walletId: options.walletId,
+		walletName: options.walletName,
+		role: options.role,
+		recoveryFile: options.recoveryFile,
+		rpcUrl: options.rpcUrl,
+		nonInteractive: true,
+		noDoctor: true,
+		noSignerHints: true
+	});
+}
+async function walletRetireCommand(runtime = defaultRuntime, options) {
+	const walletId = options.walletId.trim();
+	const successorWalletId = options.successorWalletId.trim();
+	const successorWalletName = options.successorWalletName.trim();
+	const rpcUrl = options.rpcUrl.trim();
+	if (!walletId || !successorWalletId || !successorWalletName || !rpcUrl) {
+		throw new Error("--wallet-id, --successor-wallet-id, --successor-wallet-name, and --rpc-url are required");
+	}
+	if (walletId === successorWalletId) {
+		throw new Error("Mining successor wallet id must differ from the retired wallet id");
+	}
+	if (!/^[a-zA-Z0-9_-]+$/u.test(successorWalletId)) {
+		throw new Error("--successor-wallet-id must contain only letters, numbers, hyphens, or underscores");
+	}
+	const cfg = loadConfig();
+	const effectiveEnv = {
+		...process.env,
+		...cfg.env?.vars
+	};
+	const registry = readWalletProviderRegistry(effectiveEnv);
+	const source = registry.wallets.find((entry) => entry.id === walletId);
+	if (!source || source.providerId !== "local-socket-signer" || resolveWalletUserRole(source) !== "mining") {
+		throw new Error(`active signer-owned Mining wallet not found: ${walletId}`);
+	}
+	const configuredMiningWalletId = resolveConfiguredMiningWalletId(cfg);
+	if (configuredMiningWalletId !== walletId && configuredMiningWalletId !== successorWalletId) {
+		throw new Error(`${walletId} is not the active singleton Mining wallet`);
+	}
+	if (registry.wallets.some((entry) => entry.id === successorWalletId)) {
+		throw new Error(`successor wallet id is already registered: ${successorWalletId}`);
+	}
+	const sourcePublicKey = source.addresses?.solana?.trim() ?? "";
+	if (!sourcePublicKey) {
+		throw new Error("source Mining wallet has no verified Solana address");
+	}
+	const sourceSignerWalletId = typeof source.metadata?.signerWalletId === "string" && source.metadata.signerWalletId.trim() ? source.metadata.signerWalletId.trim() : normalizeNativeSignerWalletId(source.id);
+	const successorSignerWalletId = normalizeNativeSignerWalletId(successorWalletId);
+	if (sourceSignerWalletId === successorSignerWalletId) {
+		throw new Error("Mining successor signer wallet id must be distinct");
+	}
+	const recovery = verifyMiningRecoveryPackage({
+		recoveryFile: options.recoveryFile,
+		walletId: sourceSignerWalletId,
+		publicKey: sourcePublicKey
+	});
+	const hosted = String(effectiveEnv.FASED_HOST_PROFILE ?? "").trim().toLowerCase() === "hosting";
+	const signerBinPath = hosted ? "/opt/fased/signer/fased-signerd" : resolveSignerdBinaryPath(effectiveEnv);
+	const socketFlag = hosted ? "--operator-socket" : "--control-socket";
+	const socketPath = hosted ? "/run/fased-signerd/operator.sock" : resolveLocalSignerControlSocketPath(effectiveEnv);
+	let rotation = invokeNativeSignerRotationStatus({
+		signerBinPath,
+		socketFlag,
+		socketPath,
+		sourceWalletId: sourceSignerWalletId,
+		env: effectiveEnv
+	});
+	if (rotation && rotation.successorWalletId !== successorSignerWalletId) {
+		throw new Error(`source wallet is already bound to immutable successor ${rotation.successorWalletId}`);
+	}
+	if (!rotation && configuredMiningWalletId !== walletId) {
+		throw new Error("Mining configuration changed before the signer prepared a successor");
+	}
+	let evidence;
+	if (!rotation || rotation.state !== "committed") {
+		const sourceReadiness = invokeNativeSignerWalletReadiness({
+			signerBinPath,
+			socketFlag,
+			socketPath,
+			walletId: sourceSignerWalletId,
+			env: effectiveEnv
+		});
+		if (sourceReadiness.publicKey !== sourcePublicKey || sourceReadiness.role !== "mining" || !sourceReadiness.keyReady || !sourceReadiness.policyReady || !sourceReadiness.networkReady) {
+			throw new Error("source Mining wallet is not live and role-ready in the signer");
+		}
+		const signerSOL = invokeNativeSignerBalance({
+			signerBinPath,
+			socketFlag,
+			socketPath,
+			walletId: sourceSignerWalletId,
+			publicKey: sourcePublicKey,
+			env: effectiveEnv
+		});
+		evidence = buildMiningRetirementEvidence({
+			walletId,
+			signerWalletId: sourceSignerWalletId,
+			publicKey: sourcePublicKey,
+			signerSolBalanceLamports: signerSOL,
+			liveStatus: options.liveMiningStatus,
+			env: effectiveEnv
+		});
+		rotation ??= invokeNativeSignerRotationCreate({
+			signerBinPath,
+			socketFlag,
+			socketPath,
+			sourceWalletId: sourceSignerWalletId,
+			successorWalletId: successorSignerWalletId,
+			sourcePublicKey,
+			sourceWalletVersion: Number(sourceReadiness.walletVersion),
+			sourcePolicyVersion: sourceReadiness.policyVersion,
+			env: effectiveEnv
+		});
+		if (rotation.role !== "mining" || rotation.sourcePublicKey !== sourcePublicKey || rotation.successorPublicKey === sourcePublicKey) {
+			throw new Error("signer prepared an invalid Mining successor binding");
+		}
+		let successorReadiness = invokeNativeSignerWalletReadiness({
+			signerBinPath,
+			socketFlag,
+			socketPath,
+			walletId: successorSignerWalletId,
+			env: effectiveEnv
+		});
+		let successorNetwork = {
+			version: successorReadiness.networkVersion,
+			hash: successorReadiness.networkHash ?? "",
+			ready: successorReadiness.networkReady
+		};
+		if (successorNetwork.version === 0) {
+			successorNetwork = invokeNativeSignerNetworkSetPrimary({
+				signerBinPath,
+				socketFlag,
+				socketPath,
+				walletId: successorSignerWalletId,
+				primaryRpcUrl: rpcUrl,
+				expectedVersion: 0,
+				env: effectiveEnv
+			});
+		}
+		if (!successorNetwork.ready || !successorNetwork.hash) {
+			throw new Error("Mining successor RPC is not verified and ready");
+		}
+		rotation = invokeNativeSignerRotationCommit({
+			signerBinPath,
+			socketFlag,
+			socketPath,
+			rotation,
+			successorNetworkVersion: successorNetwork.version,
+			successorNetworkHash: successorNetwork.hash,
+			recoveryPackageHash: recovery.packageHash,
+			safetyEvidence: evidence,
+			env: effectiveEnv
+		});
+		successorReadiness = invokeNativeSignerWalletReadiness({
+			signerBinPath,
+			socketFlag,
+			socketPath,
+			walletId: successorSignerWalletId,
+			env: effectiveEnv
+		});
+		if (rotation.state !== "committed" || successorReadiness.publicKey !== rotation.successorPublicKey || successorReadiness.role !== "mining" || successorReadiness.operationLane !== "mining-typed-sat" || !successorReadiness.ready || successorReadiness.policyHash !== rotation.successorActivatedPolicyHash) {
+			throw new Error("Mining successor did not become authoritatively role-ready after retirement");
+		}
+	}
+	if (rotation.state !== "committed" || rotation.recoveryPackageHash !== recovery.packageHash || !rotation.sourceRetiredPolicyHash || !rotation.successorActivatedPolicyHash || !rotation.safetyEvidenceHash) {
+		throw new Error("signer retirement acknowledgement is incomplete");
+	}
+	const successorReadiness = invokeNativeSignerWalletReadiness({
+		signerBinPath,
+		socketFlag,
+		socketPath,
+		walletId: successorSignerWalletId,
+		env: effectiveEnv
+	});
+	if (successorReadiness.publicKey !== rotation.successorPublicKey || successorReadiness.role !== "mining" || !successorReadiness.ready) {
+		throw new Error("committed Mining successor is not live and ready");
+	}
+	const receipt = {
+		version: 1,
+		kind: "fased-mining-wallet-retirement",
+		rotationId: rotation.rotationId,
+		committedAt: rotation.committedAt,
+		sourceWalletId: walletId,
+		sourceSignerWalletId,
+		sourcePublicKey,
+		sourceRetiredPolicyVersion: rotation.sourceRetiredPolicyVersion,
+		sourceRetiredPolicyHash: rotation.sourceRetiredPolicyHash,
+		successorWalletId,
+		successorSignerWalletId,
+		successorPublicKey: rotation.successorPublicKey,
+		successorPolicyVersion: successorReadiness.policyVersion,
+		successorPolicyHash: successorReadiness.policyHash,
+		successorNetworkVersion: successorReadiness.networkVersion,
+		successorNetworkHash: successorReadiness.networkHash,
+		recoveryPackageHash: rotation.recoveryPackageHash,
+		safetyEvidenceHash: rotation.safetyEvidenceHash,
+		balances: evidence ?? rotation.safetyEvidence ? {
+			solBalanceLamports: (evidence ?? rotation.safetyEvidence).solBalanceLamports,
+			satBalanceRaw: (evidence ?? rotation.safetyEvidence).satBalanceRaw
+		} : undefined
+	};
+	const receiptPath = writeMiningRetirementReceipt({
+		sourceWalletId: walletId,
+		receipt,
+		env: effectiveEnv
+	});
+	const currentEntry = cfg.plugins?.entries?.["sat-mining"];
+	const currentPluginConfig = currentEntry?.config && typeof currentEntry.config === "object" && !Array.isArray(currentEntry.config) ? currentEntry.config : {};
+	await writeConfigFile({
+		...cfg,
+		plugins: {
+			...cfg.plugins,
+			entries: {
+				...cfg.plugins?.entries,
+				"sat-mining": {
+					...currentEntry,
+					enabled: true,
+					config: {
+						...currentPluginConfig,
+						walletId: successorWalletId
+					}
+				}
+			}
+		}
+	});
+	replaceRetiredMiningWallet({
+		sourceWalletId: walletId,
+		signerAcknowledgement: {
+			rotationId: rotation.rotationId,
+			sourceRetiredPolicyHash: String(rotation.sourceRetiredPolicyHash),
+			successorPublicKey: rotation.successorPublicKey,
+			successorPolicyHash: successorReadiness.policyHash
+		},
+		successor: {
+			id: successorWalletId,
+			name: successorWalletName,
+			providerId: "local-socket-signer",
+			addresses: { solana: rotation.successorPublicKey },
+			metadata: {
+				role: "mining",
+				purpose: "mining",
+				keyAuthority: "signer-owned-v2",
+				signerWalletId: successorSignerWalletId,
+				policyHash: successorReadiness.policyHash,
+				policyVersion: successorReadiness.policyVersion,
+				baselineVersion: successorReadiness.baselineVersion,
+				policyState: "ready",
+				networkHash: successorReadiness.networkHash,
+				networkVersion: successorReadiness.networkVersion,
+				networkReady: true,
+				operationLane: successorReadiness.operationLane,
+				roleReady: true,
+				predecessorWalletId: walletId,
+				rotationId: rotation.rotationId
+			}
+		},
+		env: effectiveEnv
+	});
+	const result = {
+		ok: true,
+		retiredWalletId: walletId,
+		retiredAddress: sourcePublicKey,
+		successorWalletId,
+		successorAddress: rotation.successorPublicKey,
+		rotationId: rotation.rotationId,
+		receiptPath
+	};
+	if (options.json) {
+		runtime.log(JSON.stringify(result, null, 2));
+	} else {
+		runtime.log(`Retired Mining wallet ${walletId} (${sourcePublicKey}).`);
+		runtime.log(`Active Mining successor: ${successorWalletId} (${rotation.successorPublicKey}).`);
+		runtime.log(`Audit receipt: ${receiptPath}`);
+	}
+	return result;
+}
+async function walletRawExportCommand(runtime = defaultRuntime, options) {
+	const walletId = options.walletId.trim();
+	const output = options.output.trim();
+	if (!walletId) {
+		throw new Error("--wallet-id is required");
+	}
+	if (!options.acknowledgeCustodyReduction) {
+		throw new Error("--acknowledge-custody-reduction is required for raw private-key export");
+	}
+	if (!output || !path.isAbsolute(output) || path.resolve(output) !== output) {
+		throw new Error("--output must be an absolute clean path for a new owner-only keypair file");
+	}
+	const cfg = loadConfig();
+	const effectiveEnv = {
+		...process.env,
+		...cfg.env?.vars
+	};
+	const wallet = readWalletProviderRegistry(effectiveEnv).wallets.find((entry) => entry.id === walletId);
+	if (!wallet || wallet.providerId !== "local-socket-signer") {
+		throw new Error(`native signer wallet not found: ${walletId}`);
+	}
+	const publicKey = wallet.addresses?.solana?.trim() || "";
+	if (!publicKey) {
+		throw new Error(`native signer wallet ${walletId} has no verified Solana public address`);
+	}
+	const hosted = String(effectiveEnv.FASED_HOST_PROFILE ?? "").trim().toLowerCase() === "hosting";
+	const signerWalletId = typeof wallet.metadata?.signerWalletId === "string" && wallet.metadata.signerWalletId.trim() ? wallet.metadata.signerWalletId.trim() : normalizeNativeSignerWalletId(wallet.id);
+	runtime.log("WARNING: raw private-key export reduces signer custody protection.");
+	const child = spawnSync(hosted ? "/opt/fased/signer/fased-signerd" : resolveSignerdBinaryPath(effectiveEnv), [
+		"admin",
+		"wallet",
+		"export-raw",
+		hosted ? "--operator-socket" : "--control-socket",
+		hosted ? "/run/fased-signerd/operator.sock" : resolveLocalSignerControlSocketPath(effectiveEnv),
+		"--wallet-id",
+		signerWalletId,
+		"--expected-public-key",
+		publicKey,
+		"--output",
+		output,
+		"--acknowledge-custody-reduction"
+	], {
+		env: {
+			HOME: effectiveEnv.HOME,
+			LANG: effectiveEnv.LANG || "C.UTF-8",
+			PATH: "/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin"
+		},
+		stdio: "inherit",
+		timeout: 12e4
+	});
+	if (child.error) {
+		throw child.error;
+	}
+	if (child.status !== 0) {
+		throw new Error(`raw private-key export failed with exit code ${child.status ?? "unknown"}`);
+	}
+	runtime.log(`Raw private key written: ${output} (owner-only)`);
+	runtime.log(`Wallet: ${wallet.id} · Address: ${publicKey}`);
+}
 async function walletRoleSetCommand(runtime = defaultRuntime, options) {
 	const walletId = options.walletId.trim();
 	const role = normalizeWalletRoleForCli(options.role);
@@ -790,10 +1862,56 @@ async function walletRoleSetCommand(runtime = defaultRuntime, options) {
 		}, null, 2));
 		return;
 	}
-	runtime.log(`${wallet?.name ?? walletId} (${walletId}) set to ${role === "agent" ? "Agent wallet" : "Vault wallet"}${primary ? " and primary Agent fallback" : ""}.`);
+	runtime.log(`${wallet?.name ?? walletId} (${walletId}) set to ${role === "agent" ? "Agent wallet" : "Vault wallet"}${primary ? " and Default Agent wallet fallback" : ""}.`);
 }
 async function walletStatusCommand(runtime = defaultRuntime, options = {}) {
-	const status = await readWalletStatusSnapshot();
+	const config = loadConfig();
+	const effectiveEnv = {
+		...process.env,
+		...config.env?.vars
+	};
+	const hostedOperator = String(effectiveEnv.FASED_HOST_PROFILE ?? "").trim().toLowerCase() === "hosting" && effectiveEnv.FASED_GATEWAY_SERVICE !== "1";
+	if (hostedOperator) {
+		const registered = readWalletProviderRegistry(effectiveEnv).wallets.filter((wallet) => wallet.providerId === "local-socket-signer" && (!options.walletId || wallet.id === options.walletId));
+		if (options.walletId && registered.length === 0) {
+			throw new Error(`native signer wallet not found: ${options.walletId}`);
+		}
+		const wallets = registered.map((wallet) => {
+			const signerWalletId = typeof wallet.metadata?.signerWalletId === "string" && wallet.metadata.signerWalletId.trim() ? wallet.metadata.signerWalletId.trim() : normalizeNativeSignerWalletId(wallet.id);
+			return {
+				id: wallet.id,
+				name: wallet.name,
+				signer: invokeNativeSignerWalletReadiness({
+					signerBinPath: "/opt/fased/signer/fased-signerd",
+					socketFlag: "--operator-socket",
+					socketPath: "/run/fased-signerd/operator.sock",
+					walletId: signerWalletId,
+					env: effectiveEnv
+				})
+			};
+		});
+		if (options.json) {
+			runtime.log(JSON.stringify({
+				ok: true,
+				status: {
+					mode: "hosting-operator",
+					wallets
+				}
+			}, null, 2));
+			return;
+		}
+		if (wallets.length === 0) {
+			runtime.log("No signer-owned wallets are registered.");
+			return;
+		}
+		for (const wallet of wallets) {
+			runtime.log(`Wallet ${wallet.name} (${wallet.id}): ${wallet.signer.ready ? "ready" : "setup incomplete"}`);
+			runtime.log(`  signer=${wallet.signer.walletId} role=${wallet.signer.role} lane=${wallet.signer.operationLane} baseline=v${wallet.signer.baselineVersion}`);
+			runtime.log(`  key=${String(wallet.signer.keyReady)} policy=v${wallet.signer.policyVersion} ${wallet.signer.policyHash} network=v${wallet.signer.networkVersion} ${wallet.signer.networkHash ?? "unconfigured"}`);
+		}
+		return;
+	}
+	const status = await readWalletStatusSnapshot({ walletId: options.walletId });
 	if (options.json) {
 		runtime.log(JSON.stringify({
 			ok: true,
@@ -821,10 +1939,104 @@ async function walletStatusCommand(runtime = defaultRuntime, options = {}) {
 	if (status.addresses?.solana) {
 		runtime.log(`Address: ${status.addresses.solana}`);
 	}
+	for (const wallet of status.wallets ?? []) {
+		const signer = wallet.readiness.signer;
+		runtime.log(`Wallet ${wallet.name} (${wallet.id}): ${wallet.readiness.ready ? "ready" : "setup incomplete"}`);
+		if (signer) {
+			runtime.log(`  signer=${signer.walletId} role=${signer.role} lane=${signer.operationLane} baseline=v${signer.baselineVersion}`);
+			runtime.log(`  key=${String(signer.keyReady)} policy=v${signer.policyVersion} ${signer.policyHash} network=v${signer.networkVersion} ${signer.networkHash ?? "unconfigured"}`);
+		}
+		if (wallet.readiness.error) {
+			runtime.log(`  warning=${wallet.readiness.error}`);
+		}
+	}
 	if (status.error) {
 		runtime.log(`Status warning: ${status.error}`);
 	}
 }
+async function walletPolicyActivateRoleBaselineCommand(runtime = defaultRuntime, options) {
+	if (!options.confirm) {
+		throw new Error("Activate role baseline requires --confirm after reviewing the selected role");
+	}
+	const role = normalizeWalletUserRole(options.role);
+	if (!role) {
+		throw new Error("role must be one of: agent, mining, vault");
+	}
+	const registry = readWalletProviderRegistry(process.env);
+	const wallet = registry.wallets.find((entry) => entry.id === options.walletId.trim());
+	if (!wallet || wallet.providerId !== "local-socket-signer") {
+		throw new Error(`registered signer-owned wallet was not found: ${options.walletId}`);
+	}
+	const registeredRole = resolveWalletUserRole(wallet);
+	if (registeredRole && registeredRole !== role) {
+		throw new Error(`wallet ${wallet.id} has immutable role=${registeredRole}; refusing requested role=${role}`);
+	}
+	const signerWalletId = typeof wallet.metadata?.signerWalletId === "string" && wallet.metadata.signerWalletId.trim() ? wallet.metadata.signerWalletId.trim() : normalizeNativeSignerWalletId(wallet.id);
+	const socketPath = requireLocalSocketSignerPath(process.env);
+	const current = await readSignerOwnedWallet({
+		socketPath,
+		walletId: signerWalletId
+	});
+	if (current.wallet.publicKey !== wallet.addresses?.solana) {
+		throw new Error("registered wallet address does not match the signer-owned wallet");
+	}
+	if (current.policy.role !== role) {
+		throw new Error(`signer-owned wallet ${signerWalletId} has immutable role=${current.policy.role}, not ${role}`);
+	}
+	let policy = current.policy;
+	if (policy.baselineVersion === undefined || policy.baselineVersion === 0) {
+		policy = await activateSignerOwnedRoleBaseline({
+			socketPath,
+			walletId: signerWalletId,
+			role,
+			expectedPolicyVersion: policy.version
+		});
+	} else if (policy.baselineVersion !== 1) {
+		throw new Error(`signer-owned wallet ${signerWalletId} uses unsupported baseline version ${policy.baselineVersion}`);
+	}
+	const readiness = await readSignerOwnedWalletReadiness({
+		socketPath,
+		walletId: signerWalletId
+	});
+	if (readiness.publicKey !== current.wallet.publicKey || readiness.role !== role || readiness.policyHash !== policy.hash || readiness.policyVersion !== policy.version || readiness.baselineVersion !== 1) {
+		throw new Error("Setup incomplete: activated role baseline does not match live signer state");
+	}
+	upsertNamedWallet({
+		walletId: wallet.id,
+		name: wallet.name,
+		providerId: wallet.providerId,
+		addresses: wallet.addresses,
+		metadata: {
+			...wallet.metadata,
+			role,
+			purpose: role,
+			signerWalletId,
+			policyHash: readiness.policyHash,
+			policyVersion: readiness.policyVersion,
+			baselineVersion: readiness.baselineVersion,
+			policyState: readiness.policyReady ? "ready" : "setup-incomplete",
+			networkHash: readiness.networkHash,
+			networkVersion: readiness.networkVersion,
+			networkReady: readiness.networkReady,
+			operationLane: readiness.operationLane,
+			roleReady: readiness.ready
+		},
+		env: process.env
+	});
+	const payload = {
+		ok: true,
+		walletId: wallet.id,
+		signerWalletId,
+		role,
+		readiness
+	};
+	if (options.json) {
+		runtime.log(JSON.stringify(payload, null, 2));
+		return;
+	}
+	runtime.log(`Activated ${role} role baseline v${readiness.baselineVersion} for ${wallet.name} (${wallet.id}).`);
+	runtime.log(`Readiness: ${readiness.ready ? "ready" : "setup incomplete"} (${readiness.operationLane}).`);
+}
 async function walletKeystoreInitCommand(runtime = defaultRuntime, options = {}) {
 	void runtime;
 	void options;
@@ -1509,4 +2721,4 @@ async function walletInboundReconcileCommand(runtime = defaultRuntime, options =
 }
 
 //#endregion
-export { collectWalletSignerDoctorReport, walletCanaryCommand, walletInboundListCommand, walletInboundPollCommand, walletInboundReconcileCommand, walletLegacyMigrationFinalizeCommand, walletLimitOrdersConfigureCommand, walletMigrateCommand, walletPolicyProfileApplyCommand, walletProviderConfigureCommand, walletRoleSetCommand, walletRotateKeysCommand, walletSetupCommand, walletSignerDoctorCommand, walletSignerServeCommand, walletStatusCommand };
+export { collectWalletSignerDoctorReport, walletCanaryCommand, walletInboundListCommand, walletInboundPollCommand, walletInboundReconcileCommand, walletLegacyMigrationFinalizeCommand, walletLimitOrdersConfigureCommand, walletMigrateCommand, walletPolicyActivateRoleBaselineCommand, walletPolicyProfileApplyCommand, walletProviderConfigureCommand, walletRawExportCommand, walletRecoveryExportCommand, walletRecoveryImportCommand, walletRetireCommand, walletRoleSetCommand, walletRotateKeysCommand, walletRpcSetCommand, walletSetupCommand, walletSignerDoctorCommand, walletSignerServeCommand, walletStatusCommand };