@wlfi-agent/cli 1.4.13 → 1.4.14

package/src/lib/admin-setup.ts

@@ -0,0 +1,1612 @@
+import fs from 'node:fs';
+import net from 'node:net';
+import os from 'node:os';
+import path from 'node:path';
+import readline from 'node:readline';
+import { Command } from 'commander';
+import type { Hex } from 'viem';
+import { publicKeyToAddress } from 'viem/accounts';
+import {
+  defaultRustBinDir,
+  readConfig,
+  redactConfig,
+  type WlfiConfig,
+  writeConfig,
+} from '../../packages/config/src/index.js';
+import { cleanupBootstrapAgentCredentialsFile } from './bootstrap-credentials.js';
+import {
+  assertTrustedAdminDaemonSocketPath,
+  assertTrustedExecutablePath,
+  assertTrustedRootPlannedDaemonSocketPath,
+  assertTrustedRootPlannedPrivateFilePath,
+} from './fs-trust.js';
+import { DAEMON_PASSWORD_KEYCHAIN_SERVICE } from './keychain.js';
+import { resolveCliNetworkProfile } from './network-selection.js';
+import { passthroughRustBinary, RustBinaryExitError, runRustBinary } from './rust.js';
+import { createSudoSession } from './sudo.js';
+import { resolveWalletProfile } from './wallet-profile.js';
+import {
+  assertWalletSetupExecutionPreconditions,
+  buildWalletSetupAdminArgs,
+  type CompleteWalletSetupResult,
+  completeWalletSetup,
+  createWalletSetupPlan,
+  formatWalletSetupPlanText,
+  resolveWalletSetupBootstrapOutputPath,
+  resolveWalletSetupCleanupAction,
+  type WalletSetupPlan,
+} from './wallet-setup.js';
+
+const DEFAULT_LAUNCH_DAEMON_LABEL = 'com.wlfi.agent.daemon';
+const DEFAULT_SIGNER_BACKEND = 'software';
+const DEFAULT_MANAGED_BIN_DIR = '/Library/WLFI/bin';
+const DEFAULT_MANAGED_DAEMON_SOCKET = '/Library/WLFI/run/daemon.sock';
+const DEFAULT_MANAGED_STATE_FILE = '/var/db/wlfi-agent/daemon-state.enc';
+const DEFAULT_MANAGED_KEYCHAIN_HELPER = path.join(
+  DEFAULT_MANAGED_BIN_DIR,
+  `wlfi-agent-system-keychain${process.platform === 'win32' ? '.exe' : ''}`,
+);
+const MAX_SECRET_STDIN_BYTES = 16 * 1024;
+const DEFAULT_LAUNCH_DAEMON_PLIST = `/Library/LaunchDaemons/${DEFAULT_LAUNCH_DAEMON_LABEL}.plist`;
+const SPINNER_FRAMES = ['⠋', '⠙', '⠹', '⠸', '⠼', '⠴', '⠦', '⠧', '⠇', '⠏'];
+const REDACTED_SECRET_PLACEHOLDER = '<redacted>';
+const KEYCHAIN_STORED_AGENT_AUTH_TOKEN = 'stored in macOS Keychain';
+
+interface ProgressHandle {
+  succeed(message?: string): void;
+  fail(message?: string): void;
+  info(message?: string): void;
+}
+
+interface AdminSetupOptions {
+  vaultPassword?: string;
+  vaultPasswordStdin?: boolean;
+  nonInteractive?: boolean;
+  plan?: boolean;
+  yes?: boolean;
+  printAgentAuthToken?: boolean;
+  daemonSocket?: string;
+  perTxMaxWei?: string;
+  dailyMaxWei?: string;
+  weeklyMaxWei?: string;
+  maxGasPerChainWei?: string;
+  dailyMaxTxCount?: string;
+  perTxMaxFeePerGasWei?: string;
+  perTxMaxPriorityFeePerGasWei?: string;
+  perTxMaxCalldataBytes?: string;
+  token: string[];
+  allowNativeEth?: boolean;
+  network?: string;
+  rpcUrl?: string;
+  chainName?: string;
+  recipient?: string;
+  attachPolicyId: string[];
+  attachBootstrapPolicies?: boolean;
+  bootstrapOutput?: string;
+  deleteBootstrapOutput?: boolean;
+  json?: boolean;
+}
+
+interface AdminTuiOptions {
+  daemonSocket?: string;
+  bootstrapOutput?: string;
+  deleteBootstrapOutput?: boolean;
+  json?: boolean;
+  printAgentAuthToken?: boolean;
+}
+
+export interface AdminSetupPlan {
+  command: 'setup';
+  mode: 'plan';
+  daemon: {
+    launchdLabel: string;
+    socket: string;
+    stateFile: string;
+    installReady: boolean;
+    installError: string | null;
+    sourceRunnerPath: string;
+    sourceDaemonBin: string;
+    sourceKeychainHelperBin: string;
+    managedRunnerPath: string;
+    managedDaemonBin: string;
+    managedKeychainHelperBin: string;
+  };
+  existingWallet: ExistingWalletSetupTarget | null;
+  overwrite: {
+    required: boolean;
+    requiresYesInNonInteractive: boolean;
+  };
+  walletSetup: WalletSetupPlan;
+}
+
+interface LaunchDaemonAssetPaths {
+  runnerPath: string;
+  daemonBin: string;
+  keychainHelperBin: string;
+}
+
+interface ManagedDaemonInstallPreconditionDeps {
+  existsSync?: (targetPath: string) => boolean;
+  assertTrustedExecutablePath?: (targetPath: string) => void;
+  assertTrustedRootPlannedDaemonSocketPath?: (targetPath: string, label?: string) => string;
+  assertTrustedRootPlannedPrivateFilePath?: (targetPath: string, label?: string) => string;
+  resolveInstallScriptPath?: () => string;
+}
+
+interface ManagedDaemonInstallPreconditions extends LaunchDaemonAssetPaths {
+  installScript: string;
+  managedRunnerPath: string;
+  managedDaemonBin: string;
+  managedKeychainHelperBin: string;
+}
+
+interface ManagedDaemonInstallResult {
+  label: string;
+  runnerPath: string;
+  daemonBin: string;
+  stateFile: string;
+  keychainAccount: string;
+  keychainService: string;
+}
+
+interface ManagedLaunchDaemonAssetMatchDeps {
+  filesHaveIdenticalContents?: (leftPath: string, rightPath: string) => boolean;
+  resolveManagedPaths?: () => LaunchDaemonAssetPaths;
+}
+
+interface CreateAdminSetupPlanDeps {
+  readConfig?: () => WlfiConfig;
+  assertManagedDaemonInstallPreconditions?: typeof assertManagedDaemonInstallPreconditions;
+}
+
+export interface ExistingWalletSetupTarget {
+  address?: string;
+  agentKeyId?: string;
+  hasLegacyAgentAuthToken: boolean;
+}
+
+interface ConfirmAdminSetupOverwriteDeps {
+  prompt?: (query: string) => Promise<string>;
+  stderr?: Pick<NodeJS.WriteStream, 'write'>;
+}
+
+interface ResolveAdminSetupVaultPasswordDeps {
+  env?: NodeJS.ProcessEnv;
+  readTrimmedStdin?: (label: string) => Promise<string>;
+  promptHidden?: (query: string) => Promise<string>;
+}
+
+function validateSecret(value: string, label: string): string {
+  if (Buffer.byteLength(value, 'utf8') > MAX_SECRET_STDIN_BYTES) {
+    throw new Error(`${label} must not exceed ${MAX_SECRET_STDIN_BYTES} bytes`);
+  }
+  if (!value.trim()) {
+    throw new Error(`${label} must not be empty or whitespace`);
+  }
+  return value;
+}
+
+async function readTrimmedStdin(label: string): Promise<string> {
+  process.stdin.setEncoding('utf8');
+  let raw = '';
+  for await (const chunk of process.stdin) {
+    raw += chunk;
+    if (Buffer.byteLength(raw, 'utf8') > MAX_SECRET_STDIN_BYTES) {
+      throw new Error(`${label} must not exceed ${MAX_SECRET_STDIN_BYTES} bytes`);
+    }
+  }
+  return validateSecret(raw.replace(/[\r\n]+$/u, ''), label);
+}
+
+async function promptHidden(query: string): Promise<string> {
+  if (!process.stdin.isTTY || !process.stdout.isTTY) {
+    throw new Error('vault password is required; use --vault-password-stdin or a local TTY prompt');
+  }
+
+  const rl = readline.createInterface({
+    input: process.stdin,
+    output: process.stdout,
+    terminal: true,
+  }) as readline.Interface & { stdoutMuted?: boolean; _writeToOutput?: (value: string) => void };
+
+  rl.stdoutMuted = true;
+  rl._writeToOutput = (value: string) => {
+    if (value.includes(query)) {
+      (rl as unknown as { output: NodeJS.WritableStream }).output.write(value);
+      return;
+    }
+    if (!rl.stdoutMuted) {
+      (rl as unknown as { output: NodeJS.WritableStream }).output.write(value);
+    }
+  };
+
+  const answer = await new Promise<string>((resolve) => {
+    rl.question(query, resolve);
+  });
+  rl.close();
+  process.stdout.write('\n');
+  return validateSecret(answer, 'vault password');
+}
+
+async function promptVisible(query: string, nonInteractiveError: string): Promise<string> {
+  if (!process.stdin.isTTY || !process.stdout.isTTY) {
+    throw new Error(nonInteractiveError);
+  }
+
+  const rl = readline.createInterface({
+    input: process.stdin,
+    output: process.stdout,
+    terminal: true,
+  });
+
+  const answer = await new Promise<string>((resolve) => {
+    rl.question(query, resolve);
+  });
+  rl.close();
+  return answer.trim();
+}
+
+function deriveWalletAddress(vaultPublicKey: string | undefined): string | undefined {
+  const normalized = vaultPublicKey?.trim();
+  if (!normalized) {
+    return undefined;
+  }
+  try {
+    return publicKeyToAddress(
+      (normalized.startsWith('0x') ? normalized : `0x${normalized}`) as Hex,
+    );
+  } catch {
+    return undefined;
+  }
+}
+
+export function resolveExistingWalletSetupTarget(
+  config: WlfiConfig,
+): ExistingWalletSetupTarget | null {
+  const address =
+    config.wallet?.address?.trim() || deriveWalletAddress(config.wallet?.vaultPublicKey);
+  const agentKeyId = config.agentKeyId?.trim() || config.wallet?.agentKeyId?.trim();
+  const hasLegacyAgentAuthToken = Boolean(config.agentAuthToken?.trim());
+
+  if (!address && !agentKeyId && !hasLegacyAgentAuthToken) {
+    return null;
+  }
+
+  return {
+    address: address || undefined,
+    agentKeyId: agentKeyId || undefined,
+    hasLegacyAgentAuthToken,
+  };
+}
+
+export async function confirmAdminSetupOverwrite(
+  options: Pick<AdminSetupOptions, 'yes' | 'nonInteractive'>,
+  config: WlfiConfig,
+  deps: ConfirmAdminSetupOverwriteDeps = {},
+): Promise<void> {
+  const existing = resolveExistingWalletSetupTarget(config);
+  if (!existing || options.yes) {
+    return;
+  }
+  if (options.nonInteractive) {
+    throw new Error(
+      '`wlfi-agent admin setup` would overwrite the existing wallet; rerun with --yes in non-interactive mode',
+    );
+  }
+
+  const stderr = deps.stderr ?? process.stderr;
+  stderr.write(
+    'warning: admin setup will overwrite the current local wallet metadata and agent credentials.\n',
+  );
+  if (existing.address) {
+    stderr.write(`current address: ${existing.address}\n`);
+  }
+  if (existing.agentKeyId) {
+    stderr.write(`current agent key id: ${existing.agentKeyId}\n`);
+  }
+  if (existing.hasLegacyAgentAuthToken) {
+    stderr.write('legacy agent auth token is still present in config.json\n');
+  }
+
+  const confirmation = await (
+    deps.prompt ??
+    ((query: string) =>
+      promptVisible(
+        query,
+        '`wlfi-agent admin setup` requires --yes in non-interactive environments when overwriting an existing wallet',
+      ))
+  )('Type OVERWRITE to replace the current local wallet: ');
+  if (confirmation !== 'OVERWRITE') {
+    throw new Error('admin setup aborted');
+  }
+}
+
+export async function resolveAdminSetupVaultPassword(
+  options: Pick<AdminSetupOptions, 'vaultPassword' | 'vaultPasswordStdin' | 'nonInteractive'>,
+  deps: ResolveAdminSetupVaultPasswordDeps = {},
+): Promise<string> {
+  const env = deps.env ?? process.env;
+  const readVaultPasswordFromStdin = deps.readTrimmedStdin ?? readTrimmedStdin;
+  const promptForVaultPassword = deps.promptHidden ?? promptHidden;
+
+  if (options.vaultPassword && options.vaultPasswordStdin) {
+    throw new Error('--vault-password conflicts with --vault-password-stdin');
+  }
+  if (options.vaultPassword) {
+    validateSecret(options.vaultPassword, 'vault password');
+    throw new Error(
+      'insecure --vault-password is disabled; use --vault-password-stdin or a local TTY prompt',
+    );
+  }
+  if (options.vaultPasswordStdin) {
+    return readVaultPasswordFromStdin('vault password');
+  }
+  if (Object.hasOwn(env, 'WLFI_VAULT_PASSWORD')) {
+    validateSecret(env.WLFI_VAULT_PASSWORD ?? '', 'vault password');
+    throw new Error(
+      'WLFI_VAULT_PASSWORD is disabled for security; use --vault-password-stdin or a local TTY prompt',
+    );
+  }
+  if (options.nonInteractive) {
+    throw new Error(
+      'vault password is required in non-interactive mode; use --vault-password-stdin',
+    );
+  }
+  return promptForVaultPassword('Vault password (input hidden; nothing will be echoed): ');
+}
+
+function resolveDaemonSocket(optionValue: string | undefined): string {
+  return path.resolve(optionValue?.trim() || DEFAULT_MANAGED_DAEMON_SOCKET);
+}
+
+function resolveStateFile(): string {
+  return path.resolve(DEFAULT_MANAGED_STATE_FILE);
+}
+
+export function createAdminSetupPlan(
+  options: AdminSetupOptions,
+  deps: CreateAdminSetupPlanDeps = {},
+): AdminSetupPlan {
+  if (options.rpcUrl && !options.network) {
+    throw new Error('--rpc-url requires --network');
+  }
+  if (options.chainName && !options.network) {
+    throw new Error('--chain-name requires --network');
+  }
+
+  const loadConfig = deps.readConfig ?? readConfig;
+  const checkManagedDaemonInstallPreconditions =
+    deps.assertManagedDaemonInstallPreconditions ?? assertManagedDaemonInstallPreconditions;
+  const config = loadConfig();
+  const daemonSocket = resolveDaemonSocket(options.daemonSocket);
+  const stateFile = resolveStateFile();
+  const sourcePaths = resolveSourceLaunchDaemonPaths(config);
+  const managedPaths = resolveManagedLaunchDaemonPaths();
+  let installReady = true;
+  let installError: string | null = null;
+
+  try {
+    checkManagedDaemonInstallPreconditions(config, daemonSocket, stateFile);
+  } catch (error) {
+    installReady = false;
+    installError = renderError(error);
+  }
+
+  const existingWallet = resolveExistingWalletSetupTarget(config);
+
+  return {
+    command: 'setup',
+    mode: 'plan',
+    daemon: {
+      launchdLabel: DEFAULT_LAUNCH_DAEMON_LABEL,
+      socket: daemonSocket,
+      stateFile,
+      installReady,
+      installError,
+      sourceRunnerPath: sourcePaths.runnerPath,
+      sourceDaemonBin: sourcePaths.daemonBin,
+      sourceKeychainHelperBin: sourcePaths.keychainHelperBin,
+      managedRunnerPath: managedPaths.runnerPath,
+      managedDaemonBin: managedPaths.daemonBin,
+      managedKeychainHelperBin: managedPaths.keychainHelperBin,
+    },
+    existingWallet,
+    overwrite: {
+      required: existingWallet !== null,
+      requiresYesInNonInteractive:
+        existingWallet !== null && Boolean(options.nonInteractive) && !options.yes,
+    },
+    walletSetup: createWalletSetupPlan(
+      {
+        vaultPasswordStdin: options.vaultPasswordStdin,
+        nonInteractive: options.nonInteractive,
+        daemonSocket,
+        perTxMaxWei: options.perTxMaxWei,
+        dailyMaxWei: options.dailyMaxWei,
+        weeklyMaxWei: options.weeklyMaxWei,
+        maxGasPerChainWei: options.maxGasPerChainWei,
+        dailyMaxTxCount: options.dailyMaxTxCount,
+        perTxMaxFeePerGasWei: options.perTxMaxFeePerGasWei,
+        perTxMaxPriorityFeePerGasWei: options.perTxMaxPriorityFeePerGasWei,
+        perTxMaxCalldataBytes: options.perTxMaxCalldataBytes,
+        token: options.token,
+        allowNativeEth: options.allowNativeEth,
+        network: options.network,
+        rpcUrl: options.rpcUrl,
+        chainName: options.chainName,
+        recipient: options.recipient,
+        attachPolicyId: options.attachPolicyId,
+        attachBootstrapPolicies: options.attachBootstrapPolicies,
+        bootstrapOutputPath: options.bootstrapOutput,
+        deleteBootstrapOutput: options.deleteBootstrapOutput,
+      },
+      {
+        readConfig: () => config,
+      },
+    ),
+  };
+}
+
+function formatAdminSetupExistingWallet(plan: AdminSetupPlan): string[] {
+  if (!plan.existingWallet) {
+    return ['Existing Wallet', '- none'];
+  }
+
+  return [
+    'Existing Wallet',
+    `- Address: ${plan.existingWallet.address ?? 'unknown'}`,
+    `- Agent Key ID: ${plan.existingWallet.agentKeyId ?? 'unknown'}`,
+    `- Legacy Config Token Present: ${plan.existingWallet.hasLegacyAgentAuthToken ? 'yes' : 'no'}`,
+  ];
+}
+
+export function formatAdminSetupPlanText(plan: AdminSetupPlan): string {
+  const lines = [
+    'Admin Setup Preview',
+    `LaunchDaemon Install: ${plan.daemon.installReady ? 'ready' : 'blocked'}`,
+    plan.daemon.installError ? `Install Error: ${plan.daemon.installError}` : null,
+    `Managed Socket: ${plan.daemon.socket}`,
+    `Managed State File: ${plan.daemon.stateFile}`,
+    `LaunchDaemon Label: ${plan.daemon.launchdLabel}`,
+    '',
+    ...formatAdminSetupExistingWallet(plan),
+    `Overwrite Confirmation Required: ${plan.overwrite.required ? 'yes' : 'no'}`,
+    `Non-interactive Requires --yes: ${plan.overwrite.requiresYesInNonInteractive ? 'yes' : 'no'}`,
+    '',
+    formatWalletSetupPlanText(plan.walletSetup),
+  ];
+
+  return lines.filter((line): line is string => line !== null).join('\n');
+}
+
+function backfillPersistedWalletProfileForTui(config: WlfiConfig): WlfiConfig {
+  if (!config.wallet || config.wallet.vaultKeyId) {
+    return config;
+  }
+
+  let resolvedWallet: ReturnType<typeof resolveWalletProfile>;
+  try {
+    resolvedWallet = resolveWalletProfile(config);
+  } catch {
+    return config;
+  }
+
+  if (!resolvedWallet.vaultKeyId) {
+    return config;
+  }
+
+  return writeConfig({
+    agentKeyId: config.agentKeyId ?? resolvedWallet.agentKeyId,
+    wallet: resolvedWallet,
+  });
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null;
+}
+
+function asOptionalRecord(value: unknown): Record<string, unknown> {
+  return isRecord(value) ? value : {};
+}
+
+function isFinalAdminCommandPayload(payload: unknown): payload is Record<string, unknown> {
+  return (
+    isRecord(payload) &&
+    (payload.command === 'setup' || payload.command === 'tui') &&
+    payload.mode !== 'plan'
+  );
+}
+
+export function prepareAdminCommandOutputPayload(
+  payload: unknown,
+  includeSecrets = false,
+): unknown {
+  if (!isRecord(payload)) {
+    return payload;
+  }
+
+  const prepared = { ...payload };
+  for (const [fieldName, redactedFieldName] of [['vaultPrivateKey', 'vaultPrivateKeyRedacted']] as const) {
+    const value = prepared[fieldName];
+    if (typeof value === 'string' && value.trim()) {
+      prepared[fieldName] = REDACTED_SECRET_PLACEHOLDER;
+      prepared[redactedFieldName] = true;
+    }
+  }
+
+  if (!includeSecrets) {
+    for (const [fieldName, redactedFieldName] of [['agentAuthToken', 'agentAuthTokenRedacted']] as const) {
+      const value = prepared[fieldName];
+      if (typeof value === 'string' && value.trim()) {
+        prepared[fieldName] = REDACTED_SECRET_PLACEHOLDER;
+        prepared[redactedFieldName] = true;
+      }
+    }
+  }
+
+  return prepared;
+}
+
+export function formatAdminCommandOutput(
+  payload: unknown,
+  options: { includeSecrets?: boolean } = {},
+): string {
+  if (typeof payload === 'string') {
+    return payload;
+  }
+
+  const prepared = prepareAdminCommandOutputPayload(payload, options.includeSecrets ?? false);
+  if (!isRecord(prepared)) {
+    return JSON.stringify(prepared, null, 2);
+  }
+
+  if (prepared.command === 'tui' && prepared.canceled === true) {
+    return 'tui canceled';
+  }
+
+  const keychain = asOptionalRecord(prepared.keychain);
+  const config = asOptionalRecord(prepared.config);
+  const daemon = asOptionalRecord(prepared.daemon);
+  const vaultPublicKey = String(prepared.vaultPublicKey ?? '').trim();
+  const agentAuthToken = String(prepared.agentAuthToken ?? '').trim();
+  const includeSecrets = options.includeSecrets ?? false;
+
+  let addressLine: string | null = null;
+  if (vaultPublicKey) {
+    const normalizedPublicKey = (
+      vaultPublicKey.startsWith('0x') ? vaultPublicKey : `0x${vaultPublicKey}`
+    ) as Hex;
+    addressLine = `address: ${publicKeyToAddress(normalizedPublicKey)}`;
+  }
+
+  const daemonSocket = String(daemon.daemonSocket ?? config.daemonSocket ?? '').trim();
+  const stateFile = String(daemon.stateFile ?? config.stateFile ?? '').trim();
+  const chainName = String(config.chainName ?? prepared.networkScope ?? 'unconfigured').trim();
+  const keychainService = String(keychain.service ?? '').trim();
+  const title = prepared.command === 'tui' ? 'tui complete' : 'setup complete';
+
+  const lines = [
+    title,
+    addressLine,
+    typeof prepared.vaultKeyId === 'string' && prepared.vaultKeyId.trim()
+      ? `vault key id: ${prepared.vaultKeyId}`
+      : null,
+    typeof prepared.agentKeyId === 'string' && prepared.agentKeyId.trim()
+      ? `agent key id: ${prepared.agentKeyId}`
+      : null,
+    daemonSocket ? `daemon socket: ${daemonSocket}` : null,
+    stateFile ? `state file: ${stateFile}` : null,
+    `chain: ${chainName || 'unconfigured'}`,
+    includeSecrets
+      ? agentAuthToken
+        ? `agent auth token: ${agentAuthToken}`
+        : null
+      : `agent auth token: ${KEYCHAIN_STORED_AGENT_AUTH_TOKEN}`,
+    keychainService ? `keychain service: ${keychainService}` : null,
+  ].filter((line): line is string => Boolean(line && !line.endsWith(': ')));
+
+  if (includeSecrets && agentAuthToken) {
+    lines.push('warning: keep the agent auth token carefully.');
+  }
+
+  return lines.join('\n');
+}
+
+function printCliPayload(payload: unknown, asJson: boolean, includeSecrets = false): void {
+  const prepared = isFinalAdminCommandPayload(payload)
+    ? prepareAdminCommandOutputPayload(payload, includeSecrets)
+    : payload;
+
+  if (asJson) {
+    process.stdout.write(`${JSON.stringify(prepared, null, 2)}\n`);
+    return;
+  }
+  if (typeof prepared === 'string') {
+    process.stdout.write(`${prepared}\n`);
+    return;
+  }
+  if (isFinalAdminCommandPayload(prepared)) {
+    process.stdout.write(`${formatAdminCommandOutput(prepared, { includeSecrets })}\n`);
+    return;
+  }
+  process.stdout.write(`${JSON.stringify(prepared, null, 2)}\n`);
+}
+
+function resolveRustBinDir(config: WlfiConfig): string {
+  return path.resolve(config.rustBinDir || defaultRustBinDir());
+}
+
+function resolveSourceLaunchDaemonPaths(config: WlfiConfig): LaunchDaemonAssetPaths {
+  const rustBinDir = resolveRustBinDir(config);
+  return {
+    runnerPath: path.join(rustBinDir, 'run-wlfi-agent-daemon.sh'),
+    daemonBin: path.join(
+      rustBinDir,
+      `wlfi-agent-daemon${process.platform === 'win32' ? '.exe' : ''}`,
+    ),
+    keychainHelperBin: path.join(
+      rustBinDir,
+      `wlfi-agent-system-keychain${process.platform === 'win32' ? '.exe' : ''}`,
+    ),
+  };
+}
+
+export function resolveManagedLaunchDaemonPaths(): LaunchDaemonAssetPaths {
+  return {
+    runnerPath: path.join(DEFAULT_MANAGED_BIN_DIR, 'run-wlfi-agent-daemon.sh'),
+    daemonBin: path.join(
+      DEFAULT_MANAGED_BIN_DIR,
+      `wlfi-agent-daemon${process.platform === 'win32' ? '.exe' : ''}`,
+    ),
+    keychainHelperBin: DEFAULT_MANAGED_KEYCHAIN_HELPER,
+  };
+}
+
+function resolveLaunchDaemonInstallScriptPath(): string {
+  const candidates = [
+    path.resolve(__dirname, '../scripts/launchd/install-user-daemon.sh'),
+    path.resolve(__dirname, '../../scripts/launchd/install-user-daemon.sh'),
+    path.resolve(process.cwd(), 'scripts/launchd/install-user-daemon.sh'),
+  ];
+
+  for (const candidate of candidates) {
+    if (fs.existsSync(candidate)) {
+      return candidate;
+    }
+  }
+
+  return candidates[0];
+}
+
+function filesHaveIdenticalContents(leftPath: string, rightPath: string): boolean {
+  try {
+    const leftStats = fs.statSync(leftPath);
+    const rightStats = fs.statSync(rightPath);
+    if (!leftStats.isFile() || !rightStats.isFile() || leftStats.size !== rightStats.size) {
+      return false;
+    }
+
+    return fs.readFileSync(leftPath).equals(fs.readFileSync(rightPath));
+  } catch {
+    return false;
+  }
+}
+
+export function managedLaunchDaemonAssetsMatchSource(
+  config: WlfiConfig,
+  deps: ManagedLaunchDaemonAssetMatchDeps = {},
+): boolean {
+  const sourcePaths = resolveSourceLaunchDaemonPaths(config);
+  const managedPaths = (deps.resolveManagedPaths ?? resolveManagedLaunchDaemonPaths)();
+  const compareFileContents = deps.filesHaveIdenticalContents ?? filesHaveIdenticalContents;
+  return (
+    compareFileContents(sourcePaths.runnerPath, managedPaths.runnerPath) &&
+    compareFileContents(sourcePaths.daemonBin, managedPaths.daemonBin) &&
+    compareFileContents(sourcePaths.keychainHelperBin, managedPaths.keychainHelperBin)
+  );
+}
+
+export function assertManagedDaemonInstallPreconditions(
+  config: WlfiConfig,
+  daemonSocket: string,
+  stateFile: string,
+  deps: ManagedDaemonInstallPreconditionDeps = {},
+): ManagedDaemonInstallPreconditions {
+  const existsSync = deps.existsSync ?? fs.existsSync;
+  const trustExecutablePath = deps.assertTrustedExecutablePath ?? assertTrustedExecutablePath;
+  const trustDaemonSocketPath =
+    deps.assertTrustedRootPlannedDaemonSocketPath ?? assertTrustedRootPlannedDaemonSocketPath;
+  const trustStateFilePath =
+    deps.assertTrustedRootPlannedPrivateFilePath ?? assertTrustedRootPlannedPrivateFilePath;
+  const installScript = (deps.resolveInstallScriptPath ?? resolveLaunchDaemonInstallScriptPath)();
+  const sourcePaths = resolveSourceLaunchDaemonPaths(config);
+  const managedPaths = resolveManagedLaunchDaemonPaths();
+
+  if (!existsSync(sourcePaths.runnerPath)) {
+    throw new Error(
+      `daemon runner is not installed at ${sourcePaths.runnerPath}; rerun npm run install:rust-binaries`,
+    );
+  }
+  if (!existsSync(sourcePaths.daemonBin)) {
+    throw new Error(
+      `daemon binary is not installed at ${sourcePaths.daemonBin}; rerun npm run install:rust-binaries`,
+    );
+  }
+  if (!existsSync(sourcePaths.keychainHelperBin)) {
+    throw new Error(
+      `daemon keychain helper is not installed at ${sourcePaths.keychainHelperBin}; rerun npm run install:rust-binaries`,
+    );
+  }
+  if (!existsSync(installScript)) {
+    throw new Error(`launchd install helper is not installed at ${installScript}`);
+  }
+
+  trustExecutablePath(sourcePaths.runnerPath);
+  trustExecutablePath(sourcePaths.daemonBin);
+  trustExecutablePath(sourcePaths.keychainHelperBin);
+  trustExecutablePath(installScript);
+  trustDaemonSocketPath(daemonSocket, 'Managed daemon socket');
+  trustStateFilePath(stateFile, 'Managed daemon state file');
+
+  return {
+    ...sourcePaths,
+    installScript,
+    managedRunnerPath: managedPaths.runnerPath,
+    managedDaemonBin: managedPaths.daemonBin,
+    managedKeychainHelperBin: managedPaths.keychainHelperBin,
+  };
+}
+
+function renderError(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}
+
+function createProgress(message: string, enabled = true): ProgressHandle {
+  if (!enabled) {
+    return {
+      succeed() {},
+      fail() {},
+      info() {},
+    };
+  }
+
+  if (!process.stderr.isTTY) {
+    process.stderr.write(`==> ${message}
+`);
+    return {
+      succeed(finalMessage = message) {
+        process.stderr.write(`✓ ${finalMessage}
+`);
+      },
+      fail(finalMessage = `${message} failed`) {
+        process.stderr.write(`✗ ${finalMessage}
+`);
+      },
+      info(finalMessage = message) {
+        process.stderr.write(`• ${finalMessage}
+`);
+      },
+    };
+  }
+
+  let frameIndex = 0;
+  const render = (prefix: string, currentMessage: string) => {
+    process.stderr.write(`\r\u001b[2K${prefix} ${currentMessage}`);
+  };
+
+  render(SPINNER_FRAMES[frameIndex], message);
+  const timer = setInterval(() => {
+    frameIndex = (frameIndex + 1) % SPINNER_FRAMES.length;
+    render(SPINNER_FRAMES[frameIndex], message);
+  }, 80);
+
+  const stop = (prefix: string, finalMessage: string) => {
+    clearInterval(timer);
+    render(prefix, finalMessage);
+    process.stderr.write('\n');
+  };
+
+  return {
+    succeed(finalMessage = message) {
+      stop('✓', finalMessage);
+    },
+    fail(finalMessage = `${message} failed`) {
+      stop('✗', finalMessage);
+    },
+    info(finalMessage = message) {
+      stop('•', finalMessage);
+    },
+  };
+}
+
+async function daemonAcceptsVaultPassword(
+  config: WlfiConfig,
+  daemonSocket: string,
+  vaultPassword: string,
+): Promise<boolean> {
+  try {
+    await runRustBinary(
+      'wlfi-agent-admin',
+      [
+        '--json',
+        '--non-interactive',
+        '--vault-password-stdin',
+        '--daemon-socket',
+        daemonSocket,
+        'get-relay-config',
+      ],
+      config,
+      {
+        stdin: `${vaultPassword}\n`,
+        preSuppliedSecretStdin: 'vaultPassword',
+        scrubSensitiveEnv: true,
+      },
+    );
+    return true;
+  } catch (error) {
+    if (error instanceof RustBinaryExitError) {
+      const output = `${error.stderr}\n${error.stdout}`;
+      if (/authentication failed/iu.test(output)) {
+        return false;
+      }
+    }
+    throw error;
+  }
+}
+
+const sudoSession = createSudoSession({
+  promptPassword: async () =>
+    await promptHidden(
+      'Root password (input hidden; required to install or recover the root daemon): ',
+    ),
+});
+
+async function managedStateFileExists(stateFile: string): Promise<boolean> {
+  const result = await sudoSession.run(['/bin/test', '-e', stateFile]);
+  if (result.code === 0) {
+    return true;
+  }
+  if (
+    result.code === 1 &&
+    !/password is required|try again|authentication failed|sorry/iu.test(result.stderr)
+  ) {
+    return false;
+  }
+  throw new Error(
+    result.stderr.trim() ||
+      result.stdout.trim() ||
+      `failed to inspect managed daemon state file '${stateFile}' (exit code ${result.code})`,
+  );
+}
+
+async function waitForTrustedDaemonSocket(targetPath: string, timeoutMs = 15_000): Promise<void> {
+  async function canConnect(socketPath: string): Promise<boolean> {
+    return new Promise<boolean>((resolve) => {
+      const socket = net.createConnection(socketPath);
+      let settled = false;
+
+      const finish = (result: boolean) => {
+        if (settled) {
+          return;
+        }
+        settled = true;
+        socket.destroy();
+        resolve(result);
+      };
+
+      socket.once('connect', () => finish(true));
+      socket.once('error', (error: NodeJS.ErrnoException) => {
+        if (error.code === 'ECONNREFUSED' || error.code === 'ENOENT') {
+          finish(false);
+          return;
+        }
+        finish(false);
+      });
+      socket.setTimeout(500, () => finish(false));
+    });
+  }
+
+  const started = Date.now();
+  while (Date.now() - started < timeoutMs) {
+    try {
+      const resolvedPath = assertTrustedAdminDaemonSocketPath(targetPath);
+      if (await canConnect(resolvedPath)) {
+        return;
+      }
+    } catch {}
+    await new Promise((resolve) => setTimeout(resolve, 250));
+  }
+
+  const resolvedPath = assertTrustedAdminDaemonSocketPath(targetPath);
+  if (!(await canConnect(resolvedPath))) {
+    throw new Error(`daemon socket '${resolvedPath}' is present but not accepting connections yet`);
+  }
+}
+
+function plistContainsValue(plistContents: string, value: string): boolean {
+  return plistContents.includes(`<string>${value}</string>`);
+}
+
+function resolveInstalledLaunchDaemonPaths(
+  config: WlfiConfig,
+  plistContents: string,
+): LaunchDaemonAssetPaths | null {
+  const sourcePaths = resolveSourceLaunchDaemonPaths(config);
+  const managedPaths = resolveManagedLaunchDaemonPaths();
+
+  if (
+    plistContainsValue(plistContents, sourcePaths.runnerPath) &&
+    plistContainsValue(plistContents, sourcePaths.daemonBin) &&
+    plistContainsValue(plistContents, sourcePaths.keychainHelperBin)
+  ) {
+    return sourcePaths;
+  }
+
+  if (
+    plistContainsValue(plistContents, managedPaths.runnerPath) &&
+    plistContainsValue(plistContents, managedPaths.daemonBin) &&
+    plistContainsValue(plistContents, managedPaths.keychainHelperBin)
+  ) {
+    return managedPaths;
+  }
+
+  return null;
+}
+
+function isManagedDaemonInstallCurrent(
+  config: WlfiConfig,
+  daemonSocket: string,
+  stateFile: string,
+): boolean {
+  const sourcePaths = resolveSourceLaunchDaemonPaths(config);
+  const keychainAccount = os.userInfo().username;
+  const expectedAdminUid = String(process.getuid?.() ?? process.geteuid?.() ?? 0);
+
+  if (!fs.existsSync(DEFAULT_LAUNCH_DAEMON_PLIST)) {
+    return false;
+  }
+  if (
+    !fs.existsSync(sourcePaths.runnerPath) ||
+    !fs.existsSync(sourcePaths.daemonBin) ||
+    !fs.existsSync(sourcePaths.keychainHelperBin)
+  ) {
+    return false;
+  }
+
+  let plistContents: string;
+  try {
+    plistContents = fs.readFileSync(DEFAULT_LAUNCH_DAEMON_PLIST, 'utf8');
+  } catch {
+    return false;
+  }
+
+  const installedPaths = resolveInstalledLaunchDaemonPaths(config, plistContents);
+  if (!installedPaths) {
+    return false;
+  }
+  if (
+    !fs.existsSync(installedPaths.runnerPath) ||
+    !fs.existsSync(installedPaths.daemonBin) ||
+    !fs.existsSync(installedPaths.keychainHelperBin)
+  ) {
+    return false;
+  }
+  if (!filesHaveIdenticalContents(sourcePaths.runnerPath, installedPaths.runnerPath)) {
+    return false;
+  }
+  if (!filesHaveIdenticalContents(sourcePaths.daemonBin, installedPaths.daemonBin)) {
+    return false;
+  }
+  if (
+    !filesHaveIdenticalContents(sourcePaths.keychainHelperBin, installedPaths.keychainHelperBin)
+  ) {
+    return false;
+  }
+
+  return [
+    DEFAULT_LAUNCH_DAEMON_LABEL,
+    installedPaths.runnerPath,
+    installedPaths.daemonBin,
+    installedPaths.keychainHelperBin,
+    daemonSocket,
+    stateFile,
+    DAEMON_PASSWORD_KEYCHAIN_SERVICE,
+    keychainAccount,
+    DEFAULT_SIGNER_BACKEND,
+    expectedAdminUid,
+  ].every((value) => plistContainsValue(plistContents, value));
+}
+
+async function installLaunchDaemon(
+  config: WlfiConfig,
+  daemonSocket: string,
+  stateFile: string,
+  vaultPassword: string,
+): Promise<ManagedDaemonInstallResult> {
+  const installPreconditions = assertManagedDaemonInstallPreconditions(
+    config,
+    daemonSocket,
+    stateFile,
+  );
+  const keychainAccount = os.userInfo().username;
+
+  const installResult = await sudoSession.run(
+    [
+      installPreconditions.installScript,
+      '--label',
+      DEFAULT_LAUNCH_DAEMON_LABEL,
+      '--runner',
+      installPreconditions.runnerPath,
+      '--daemon-bin',
+      installPreconditions.daemonBin,
+      '--keychain-helper',
+      installPreconditions.keychainHelperBin,
+      '--state-file',
+      stateFile,
+      '--daemon-socket',
+      daemonSocket,
+      '--keychain-service',
+      DAEMON_PASSWORD_KEYCHAIN_SERVICE,
+      '--keychain-account',
+      keychainAccount,
+      '--signer-backend',
+      DEFAULT_SIGNER_BACKEND,
+      '--allow-admin-euid',
+      String(process.getuid?.() ?? process.geteuid?.() ?? 0),
+      '--allow-agent-euid',
+      String(process.getuid?.() ?? process.geteuid?.() ?? 0),
+      '--vault-password-stdin',
+    ],
+    {
+      stdin: `${vaultPassword}\n`,
+      inheritOutput: true,
+    },
+  );
+  if (installResult.code !== 0) {
+    throw new Error(
+      installResult.stderr.trim() ||
+        installResult.stdout.trim() ||
+        `sudo exited with code ${installResult.code}`,
+    );
+  }
+
+  return {
+    label: DEFAULT_LAUNCH_DAEMON_LABEL,
+    runnerPath: installPreconditions.managedRunnerPath,
+    daemonBin: installPreconditions.managedDaemonBin,
+    stateFile,
+    keychainAccount,
+    keychainService: DAEMON_PASSWORD_KEYCHAIN_SERVICE,
+  };
+}
+
+async function runAdminSetup(options: AdminSetupOptions): Promise<void> {
+  if (options.plan) {
+    const plan = createAdminSetupPlan(options);
+    printCliPayload(options.json ? plan : formatAdminSetupPlanText(plan), options.json ?? false);
+    return;
+  }
+
+  if (options.rpcUrl && !options.network) {
+    throw new Error('--rpc-url requires --network');
+  }
+  if (options.chainName && !options.network) {
+    throw new Error('--chain-name requires --network');
+  }
+
+  const config = readConfig();
+  const daemonSocket = resolveDaemonSocket(options.daemonSocket);
+  const stateFile = resolveStateFile();
+  assertManagedDaemonInstallPreconditions(config, daemonSocket, stateFile);
+  await confirmAdminSetupOverwrite(options, config);
+  const vaultPassword = await resolveAdminSetupVaultPassword(options);
+  const showProgress = !options.json;
+
+  const existingDaemonProgress = createProgress('Checking existing daemon', showProgress);
+  const plistContents = fs.existsSync(DEFAULT_LAUNCH_DAEMON_PLIST)
+    ? fs.readFileSync(DEFAULT_LAUNCH_DAEMON_PLIST, 'utf8')
+    : null;
+  const installedPaths = plistContents
+    ? resolveInstalledLaunchDaemonPaths(config, plistContents)
+    : null;
+
+  let daemon: ManagedDaemonInstallResult | null = null;
+  let installIsCurrent = isManagedDaemonInstallCurrent(config, daemonSocket, stateFile);
+  let existingDaemonRejectedPassword = false;
+  let existingDaemonResponding = false;
+
+  try {
+    await waitForTrustedDaemonSocket(daemonSocket, 1_500);
+    existingDaemonResponding = true;
+    const accepted = await daemonAcceptsVaultPassword(config, daemonSocket, vaultPassword);
+    if (accepted) {
+      installIsCurrent = true;
+      daemon = {
+        label: DEFAULT_LAUNCH_DAEMON_LABEL,
+        runnerPath: installedPaths?.runnerPath ?? resolveManagedLaunchDaemonPaths().runnerPath,
+        daemonBin: installedPaths?.daemonBin ?? resolveManagedLaunchDaemonPaths().daemonBin,
+        stateFile,
+        keychainAccount: os.userInfo().username,
+        keychainService: DAEMON_PASSWORD_KEYCHAIN_SERVICE,
+      };
+      existingDaemonProgress.succeed('Existing daemon is ready and accepted the vault password');
+    } else {
+      existingDaemonRejectedPassword = true;
+      existingDaemonProgress.succeed(
+        'Existing daemon is running but needs password recovery or reinstall',
+      );
+    }
+  } catch {
+    existingDaemonProgress.succeed('No ready daemon detected; checking installation state');
+  }
+
+  if (!daemon) {
+    if (installIsCurrent && existingDaemonResponding) {
+      const currentPlistContents = fs.readFileSync(DEFAULT_LAUNCH_DAEMON_PLIST, 'utf8');
+      const currentInstalledPaths =
+        resolveInstalledLaunchDaemonPaths(config, currentPlistContents) ??
+        resolveManagedLaunchDaemonPaths();
+      daemon = {
+        label: DEFAULT_LAUNCH_DAEMON_LABEL,
+        runnerPath: currentInstalledPaths.runnerPath,
+        daemonBin: currentInstalledPaths.daemonBin,
+        stateFile,
+        keychainAccount: os.userInfo().username,
+        keychainService: DAEMON_PASSWORD_KEYCHAIN_SERVICE,
+      };
+      const installProgress = createProgress('Checking existing daemon installation', showProgress);
+      installProgress.succeed('Existing daemon install looks current');
+    } else {
+      if (installIsCurrent && !existingDaemonResponding && !options.json) {
+        process.stderr.write(
+          'Existing daemon install metadata looks current, but the daemon is not responding; setup will recover it now.\n',
+        );
+      }
+      if (!options.json && typeof process.geteuid === 'function' && process.geteuid() !== 0) {
+        process.stderr.write(
+          'Root password required: setup must install or recover the root LaunchDaemon and store the daemon password in System Keychain.\n',
+        );
+      }
+      await sudoSession.prime();
+      const installProgress = createProgress('Installing and restarting daemon', showProgress);
+      try {
+        daemon = await installLaunchDaemon(config, daemonSocket, stateFile, vaultPassword);
+        installProgress.succeed('Daemon installed and restarted');
+      } catch (error) {
+        installProgress.fail();
+        throw error;
+      }
+    }
+  }
+
+  const readyProgress = createProgress('Waiting for daemon to become ready', showProgress);
+  try {
+    await waitForTrustedDaemonSocket(daemonSocket);
+    readyProgress.succeed('Daemon is ready');
+  } catch (error) {
+    readyProgress.fail();
+    throw error;
+  }
+
+  const authProgress = createProgress('Verifying daemon vault password', showProgress);
+  let daemonAcceptedPassword: boolean;
+  try {
+    daemonAcceptedPassword = await daemonAcceptsVaultPassword(config, daemonSocket, vaultPassword);
+  } catch (error) {
+    authProgress.fail();
+    throw error;
+  }
+
+  if (!daemonAcceptedPassword) {
+    if (existingDaemonRejectedPassword) {
+      authProgress.fail('Existing daemon password does not unlock the stored daemon state');
+      throw new Error(
+        `managed daemon state already exists at ${stateFile} and is encrypted with a different vault password. Re-run setup with the original vault password, or remove/reset the managed daemon state before initializing a fresh wallet.`,
+      );
+    }
+
+    authProgress.info('Daemon rejected the requested vault password; inspecting managed state');
+    const stateProbeProgress = createProgress('Inspecting managed daemon state', showProgress);
+    let stateExists: boolean;
+    try {
+      stateExists = await managedStateFileExists(stateFile);
+      stateProbeProgress.succeed(
+        stateExists ? 'Managed daemon state already exists' : 'No managed daemon state found',
+      );
+    } catch (error) {
+      stateProbeProgress.fail();
+      throw error;
+    }
+
+    if (stateExists) {
+      authProgress.fail('Existing daemon password does not unlock the stored daemon state');
+      throw new Error(
+        `managed daemon state already exists at ${stateFile} and is encrypted with a different vault password. Re-run setup with the original vault password, or remove/reset the managed daemon state before initializing a fresh wallet.`,
+      );
+    }
+
+    authProgress.fail(
+      'Existing daemon password differs; reinstalling with the requested vault password',
+    );
+
+    if (!options.json && typeof process.geteuid === 'function' && process.geteuid() !== 0) {
+      process.stderr.write(
+        'Root password required: setup must reinstall the root LaunchDaemon to rotate the managed daemon password.\n',
+      );
+    }
+    await sudoSession.prime();
+    const reinstallProgress = createProgress(
+      'Reinstalling daemon with the requested vault password',
+      showProgress,
+    );
+    try {
+      daemon = await installLaunchDaemon(config, daemonSocket, stateFile, vaultPassword);
+      reinstallProgress.succeed('Daemon reinstalled and restarted');
+    } catch (error) {
+      reinstallProgress.fail();
+      throw error;
+    }
+
+    const restartedReadyProgress = createProgress(
+      'Waiting for restarted daemon to become ready',
+      showProgress,
+    );
+    try {
+      await waitForTrustedDaemonSocket(daemonSocket);
+      restartedReadyProgress.succeed('Restarted daemon is ready');
+    } catch (error) {
+      restartedReadyProgress.fail();
+      throw error;
+    }
+
+    const retryAuthProgress = createProgress('Re-checking daemon vault password', showProgress);
+    let retryAcceptedPassword: boolean;
+    try {
+      retryAcceptedPassword = await daemonAcceptsVaultPassword(config, daemonSocket, vaultPassword);
+    } catch (error) {
+      retryAuthProgress.fail();
+      throw error;
+    }
+
+    if (!retryAcceptedPassword) {
+      retryAuthProgress.fail();
+      throw new Error(
+        'the managed daemon still rejects the requested vault password. Re-run setup with the original vault password, or clear the managed daemon state before initializing a fresh wallet.',
+      );
+    }
+
+    retryAuthProgress.succeed('Daemon accepted the requested vault password');
+  } else {
+    authProgress.succeed('Daemon accepted the requested vault password');
+  }
+
+  writeConfig({
+    daemonSocket,
+    stateFile,
+  });
+
+  const resolvedNetwork = options.network
+    ? resolveCliNetworkProfile(options.network, config)
+    : null;
+  const resolvedNetworkId = resolvedNetwork?.chainId;
+  const resolvedChainName = options.chainName?.trim() || resolvedNetwork?.name;
+
+  assertWalletSetupExecutionPreconditions(
+    {
+      daemonSocket,
+      network: resolvedNetworkId,
+      rpcUrl: options.rpcUrl,
+    },
+    config,
+    {
+      assertTrustedDaemonSocketPath: assertTrustedAdminDaemonSocketPath,
+    },
+  );
+
+  const bootstrapOutput = resolveWalletSetupBootstrapOutputPath(options.bootstrapOutput);
+  const bootstrapInvocation = buildAdminSetupBootstrapInvocation({
+    vaultPassword,
+    daemonSocket,
+    perTxMaxWei: options.perTxMaxWei,
+    dailyMaxWei: options.dailyMaxWei,
+    weeklyMaxWei: options.weeklyMaxWei,
+    maxGasPerChainWei: options.maxGasPerChainWei,
+    dailyMaxTxCount: options.dailyMaxTxCount,
+    perTxMaxFeePerGasWei: options.perTxMaxFeePerGasWei,
+    perTxMaxPriorityFeePerGasWei: options.perTxMaxPriorityFeePerGasWei,
+    perTxMaxCalldataBytes: options.perTxMaxCalldataBytes,
+    token: options.token,
+    allowNativeEth: options.allowNativeEth,
+    network: resolvedNetworkId !== undefined ? String(resolvedNetworkId) : undefined,
+    recipient: options.recipient,
+    attachPolicyId: options.attachPolicyId,
+    attachBootstrapPolicies: options.attachBootstrapPolicies,
+    bootstrapOutputPath: bootstrapOutput.path,
+  });
+
+  const bootstrapProgress = createProgress('Setting up wallet access', showProgress);
+  try {
+    await runRustBinary('wlfi-agent-admin', bootstrapInvocation.args, config, {
+      stdin: bootstrapInvocation.stdin,
+      preSuppliedSecretStdin: 'vaultPassword',
+      scrubSensitiveEnv: true,
+    });
+  } catch (error) {
+    bootstrapProgress.fail();
+    try {
+      cleanupBootstrapAgentCredentialsFile(
+        bootstrapOutput.path,
+        resolveWalletSetupCleanupAction(
+          bootstrapOutput.autoGenerated,
+          options.deleteBootstrapOutput ?? false,
+        ),
+      );
+    } catch (error) {
+      console.error(
+        `warning: failed to scrub bootstrap output after setup failure: ${renderError(error)}`,
+      );
+    }
+    if (error instanceof RustBinaryExitError) {
+      const output = error.stderr || error.stdout;
+      if (output) {
+        process.stderr.write(output.endsWith('\n') ? output : `${output}\n`);
+      }
+      process.exitCode = error.code;
+      return;
+    }
+    throw error;
+  }
+  bootstrapProgress.succeed('Bootstrap completed');
+
+  const finalizeProgress = createProgress('Importing agent token and saving config', showProgress);
+  let summary: CompleteWalletSetupResult;
+  try {
+    summary = completeWalletSetup({
+      bootstrapOutputPath: bootstrapOutput.path,
+      cleanupAction: resolveWalletSetupCleanupAction(
+        bootstrapOutput.autoGenerated,
+        options.deleteBootstrapOutput ?? false,
+      ),
+      daemonSocket,
+      perTxMaxWei: options.perTxMaxWei,
+      dailyMaxWei: options.dailyMaxWei,
+      weeklyMaxWei: options.weeklyMaxWei,
+      maxGasPerChainWei: options.maxGasPerChainWei,
+      dailyMaxTxCount: options.dailyMaxTxCount,
+      perTxMaxFeePerGasWei: options.perTxMaxFeePerGasWei,
+      perTxMaxPriorityFeePerGasWei: options.perTxMaxPriorityFeePerGasWei,
+      perTxMaxCalldataBytes: options.perTxMaxCalldataBytes,
+      token: options.token,
+      allowNativeEth: options.allowNativeEth,
+      network: resolvedNetworkId,
+      recipient: options.recipient,
+      attachPolicyId: options.attachPolicyId,
+      attachBootstrapPolicies: options.attachBootstrapPolicies,
+      rpcUrl: options.rpcUrl,
+      chainName: resolvedChainName,
+    });
+    finalizeProgress.succeed('Agent token imported and config saved');
+  } catch (error) {
+    finalizeProgress.fail();
+    throw error;
+  }
+
+  const persistedConfig = writeConfig({
+    daemonSocket,
+    stateFile,
+  });
+
+  printCliPayload(
+    {
+      command: 'setup',
+      daemon: {
+        autostart: true,
+        label: daemon.label,
+        launchdDomain: 'system',
+        daemonSocket,
+        stateFile: daemon.stateFile,
+        runnerPath: daemon.runnerPath,
+        daemonBinary: daemon.daemonBin,
+        signerBackend: DEFAULT_SIGNER_BACKEND,
+        keychainService: daemon.keychainService,
+        keychainAccount: daemon.keychainAccount,
+      },
+      ...summary,
+      config: redactConfig(persistedConfig),
+    },
+    options.json ?? false,
+    options.printAgentAuthToken ?? false,
+  );
+}
+
+export function buildAdminTuiPassthroughArgs(input: {
+  daemonSocket?: string;
+  bootstrapOutputPath: string;
+}): string[] {
+  const args = ['--json', '--quiet', '--output', input.bootstrapOutputPath];
+  if (input.daemonSocket) {
+    args.push('--daemon-socket', input.daemonSocket);
+  }
+  args.push('tui', '--print-agent-auth-token');
+  return args;
+}
+
+export function buildAdminSetupBootstrapInvocation(input: {
+  vaultPassword: string;
+  daemonSocket: string;
+  perTxMaxWei?: string;
+  dailyMaxWei?: string;
+  weeklyMaxWei?: string;
+  maxGasPerChainWei?: string;
+  dailyMaxTxCount?: string;
+  perTxMaxFeePerGasWei?: string;
+  perTxMaxPriorityFeePerGasWei?: string;
+  perTxMaxCalldataBytes?: string;
+  token?: string[];
+  allowNativeEth?: boolean;
+  network?: string;
+  recipient?: string;
+  attachPolicyId?: string[];
+  attachBootstrapPolicies?: boolean;
+  bootstrapOutputPath: string;
+}): { args: string[]; stdin: string } {
+  return {
+    args: buildWalletSetupAdminArgs({
+      vaultPasswordStdin: true,
+      nonInteractive: true,
+      daemonSocket: input.daemonSocket,
+      perTxMaxWei: input.perTxMaxWei,
+      dailyMaxWei: input.dailyMaxWei,
+      weeklyMaxWei: input.weeklyMaxWei,
+      maxGasPerChainWei: input.maxGasPerChainWei,
+      dailyMaxTxCount: input.dailyMaxTxCount,
+      perTxMaxFeePerGasWei: input.perTxMaxFeePerGasWei,
+      perTxMaxPriorityFeePerGasWei: input.perTxMaxPriorityFeePerGasWei,
+      perTxMaxCalldataBytes: input.perTxMaxCalldataBytes,
+      token: input.token,
+      allowNativeEth: input.allowNativeEth,
+      network: input.network,
+      recipient: input.recipient,
+      attachPolicyId: input.attachPolicyId,
+      attachBootstrapPolicies: input.attachBootstrapPolicies,
+      bootstrapOutputPath: input.bootstrapOutputPath,
+    }),
+    stdin: `${validateSecret(input.vaultPassword, 'vault password')}\n`,
+  };
+}
+
+async function runAdminTui(options: AdminTuiOptions): Promise<void> {
+  const config = backfillPersistedWalletProfileForTui(readConfig());
+
+  const daemonSocket = options.daemonSocket ? resolveDaemonSocket(options.daemonSocket) : undefined;
+  const bootstrapOutput = resolveWalletSetupBootstrapOutputPath(options.bootstrapOutput);
+  const cleanupAction = resolveWalletSetupCleanupAction(
+    bootstrapOutput.autoGenerated,
+    options.deleteBootstrapOutput ?? false,
+  );
+
+  const code = await passthroughRustBinary(
+    'wlfi-agent-admin',
+    buildAdminTuiPassthroughArgs({
+      daemonSocket,
+      bootstrapOutputPath: bootstrapOutput.path,
+    }),
+    config,
+  );
+  if (code !== 0) {
+    try {
+      cleanupBootstrapAgentCredentialsFile(bootstrapOutput.path, cleanupAction);
+    } catch (error) {
+      console.error(
+        `warning: failed to scrub bootstrap output after tui failure: ${renderError(error)}`,
+      );
+    }
+    process.exitCode = code;
+    return;
+  }
+
+  if (!fs.existsSync(bootstrapOutput.path)) {
+    printCliPayload(
+      options.json ? { command: 'tui', canceled: true } : 'tui canceled',
+      options.json ?? false,
+    );
+    return;
+  }
+
+  const summary = completeWalletSetup({
+    bootstrapOutputPath: bootstrapOutput.path,
+    cleanupAction,
+    daemonSocket,
+  });
+
+  printCliPayload(
+    {
+      command: 'tui',
+      ...summary,
+    },
+    options.json ?? false,
+    options.printAgentAuthToken ?? false,
+  );
+}
+
+export async function runAdminSetupCli(argv: string[]): Promise<void> {
+  const program = new Command();
+  program
+    .name('wlfi-agent admin setup')
+    .description(
+      'Store the vault password, install the root daemon autostart, set up wallet access, and print the wallet address',
+    )
+    .option('--plan', 'Print a sanitized setup preview without prompting or mutating state', false)
+    .option('--vault-password-stdin', 'Read vault password from stdin', false)
+    .option('--non-interactive', 'Disable password prompts', false)
+    .option('-y, --yes', 'Skip the overwrite confirmation prompt', false)
+    .option('--daemon-socket <path>', 'Daemon unix socket path')
+    .option('--per-tx-max-wei <wei>', 'Per-transaction max spend in wei')
+    .option('--daily-max-wei <wei>', 'Daily max spend in wei')
+    .option('--weekly-max-wei <wei>', 'Weekly max spend in wei')
+    .option('--max-gas-per-chain-wei <wei>', 'Per-chain gas-spend ceiling in wei')
+    .option('--daily-max-tx-count <count>', 'Optional daily tx-count cap')
+    .option('--per-tx-max-fee-per-gas-wei <wei>', 'Optional max fee-per-gas cap')
+    .option('--per-tx-max-priority-fee-per-gas-wei <wei>', 'Optional max priority fee-per-gas cap')
+    .option('--per-tx-max-calldata-bytes <bytes>', 'Optional calldata size cap')
+    .option(
+      '--token <address>',
+      'Allowed ERC-20 token address',
+      (value, acc: string[]) => {
+        acc.push(value);
+        return acc;
+      },
+      [],
+    )
+    .option('--allow-native-eth', 'Allow native ETH transfers', false)
+    .option('--network <name>', 'Network name for policy scope and active config')
+    .option('--rpc-url <url>', 'Persist RPC URL for the configured active chain')
+    .option('--chain-name <name>', 'Persist chain display name for the active chain')
+    .option('--recipient <address>', 'Optional allowed recipient scope')
+    .option(
+      '--attach-policy-id <uuid>',
+      'Attach the new agent key to an existing policy id',
+      (value, acc: string[]) => {
+        acc.push(value);
+        return acc;
+      },
+      [],
+    )
+    .option(
+      '--attach-bootstrap-policies',
+      'Attach the new agent key to bootstrap-created policies',
+      false,
+    )
+    .option('--bootstrap-output <path>', 'Write temporary bootstrap JSON to this private path')
+    .option('--delete-bootstrap-output', 'Delete the bootstrap JSON after Keychain import', false)
+    .option(
+      '--print-agent-auth-token',
+      'Print the freshly issued agent auth token after importing it into macOS Keychain',
+      false,
+    )
+    .option('--json', 'Print JSON output', false)
+    .action(runAdminSetup);
+
+  await program.parseAsync(argv, { from: 'user' });
+}
+
+export async function runAdminTuiCli(argv: string[]): Promise<void> {
+  const program = new Command();
+  program
+    .name('wlfi-agent admin tui')
+    .description(
+      'Launch the interactive terminal UI, then import the new agent token and activate the new wallet locally',
+    )
+    .option('--daemon-socket <path>', 'Daemon unix socket path')
+    .option('--bootstrap-output <path>', 'Write temporary bootstrap JSON to this private path')
+    .option('--delete-bootstrap-output', 'Delete the bootstrap JSON after Keychain import', false)
+    .option(
+      '--print-agent-auth-token',
+      'Print the freshly issued agent auth token after importing it into macOS Keychain',
+      false,
+    )
+    .option('--json', 'Print JSON output', false)
+    .action(runAdminTui);
+
+  await program.parseAsync(argv, { from: 'user' });
+}